Merge pull request #274 from jingjtang/safegraph_pattern_api_docs

Add API documentation for SafeGraph Patterns

Author: krivard

docs/api/covidcast-signals/safegraph.md

@@ -4,22 +4,32 @@ parent: Data Sources and Signals
 grand_parent: COVIDcast Epidata API
 ---
 
-# SafeGraph Mobility
-
+# SafeGraph
+{: .no_toc}
 * **Source name:** `safegraph`
+
+This data source uses data reported by [SafeGraph](https://www.safegraph.com/)
+using anonymized location data from mobile phones. SafeGraph provides several different datasets to eligible researchers. We surface signals from two such datasets.
+
+## Table of contents
+{: .no_toc .text-delta}
+
+1. TOC
+{:toc}
+
+## SafeGraph Social Distancing Metrics
+
 * **First issued:** 23 June 2020
 * **Number of data revisions since 23 June 2020:** 1
 * **Date of last change:** 3 November 2020
 * **Available for:** county, state (see [geography coding docs](../covidcast_geography.md))
 
-This data source uses data reported by [SafeGraph](https://www.safegraph.com/)
-using anonymized location data from mobile phones. SafeGraph provides [social
-distancing metrics](https://docs.safegraph.com/docs/social-distancing-metrics)
-to eligible researchers who obtain an API key. SafeGraph provides this data for
-individual census block groups, using differential privacy to protect the
-privacy of individual people in the data.
+Data source based on [social
+distancing metrics](https://docs.safegraph.com/docs/social-distancing-metrics). 
+SafeGraph provides this data for
+individual census block groups, using differential privacy to protect individual people's data privacy.
 
-Delphi creates features of the Safegraph data at the census block group level,
+Delphi creates features of the SafeGraph data at the census block group level,
 then aggregates these features to the county and state levels. The aggregated
 data is freely available through the COVIDcast API.
 
@@ -51,8 +61,45 @@ weekends have substantially different values than weekdays. Users interested in
 trends, rather than mobility on one specific day, may prefer the `7dav` signals since
 averaging over the preceding 7 days removes these day-of-week effects.
 
-## Lag
+### Lag
 
 SafeGraph provides this data with a three-day lag, meaning estimates for a
 specific day are only available three days later. It may take up to an
 additional day for SafeGraph's data to be ingested into the COVIDcast API.
+
+
+## SafeGraph Weekly Patterns
+
+* **First issued:** 20 November 2020
+* **Number of data revisions since 23 June 2020:** 0
+* **Date of last change:** never
+* **Available for:** county, MSA, HRR, state (see [geography coding docs](../covidcast_geography.md))
+
+Data source based on
+[Weekly Patterns](https://docs.safegraph.com/docs/weekly-patterns) dataset. SafeGraph provides this data for
+different points of interest ([POIs](https://docs.safegraph.com/v4.0/docs#section-core-places)) considering individual census block groups, using differential privacy to protect individual people's data privacy.
+
+Delphi gathers the number of daily visits to POIs of certain types(bars, restaurants, etc.) 
+from SafeGraph's Weekly Patterns data at the 5-digit ZipCode level, then aggregates and reports these features to the county, MSA, HRR, and state levels. The aggregated data is freely available through the COVIDcast API.
+
+For precise definitions of the quantities below, consult the [SafeGraph Weekly 
+Patterns documentation](https://docs.safegraph.com/docs/weekly-patterns).
+
+| Signal | Description |
+| --- | --- |
+| `bars_visit_num` | The number of daily visits to bar-related POIs in a certain region |
+| `bars_visit_prop` | The number of daily visits to bar-related POIs in a certain region, per 100,000 population |
+| `restaurants_visit_num` | The number of daily visits to restaurant-related POIs in a certain region |
+| `restaurants_visit_prop` | The number of daily visits to restaurant-related POIs in a certain region, per 100,000 population |
+
+SafeGraph delivers the number of daily visits to U.S. POIs, the details of which are described in 
+the [Places Manual](https://readme.safegraph.com/docs/places-manual#section-placekey) dataset. 
+Delphi aggregates the number of visits to certain types of places, such as 
+bars (places with [NAICS code = 722410](https://www.census.gov/cgi-bin/sssd/naics/naicsrch?input=722410&search=2017+NAICS+Search&search=2017)) and restaurants (places with [NAICS code = 722511](https://www.census.gov/cgi-bin/sssd/naics/naicsrch)). For example, Adagio Teas is coded as a bar because it serves alcohol, while Napkin Burger is considered to be a full-service restaurant.
+More information on NAICS codes is available from the [US Census Bureau: North American Industry Classification System](https://www.census.gov/eos/www/naics/index.html).
+
+### Lag
+
+SafeGraph provides newly updated data for the previous week every Wednesday, 
+meaning estimates for a specific day are only available 3-9 days later. It may take up to an
+additional day for SafeGraph's data to be ingested into the COVIDcast API.