In 2012, Yelp partnered with the City of San Francisco and City of New York to develop the Local Inspector Value-Entry Specification (LIVES). LIVES is an open data standard which allows municipalities to publish restaurant inspection information to Yelp. Implementation
Any municipality may participate in this program. To begin this process, email us: healthscores@yelp.com. Onboarding Steps
Follow the LIVES data specification to create a feed for your location.
Host the feed on a web server for Yelp to fetch. We support both HTTP and HTTPS.
Send an email to healthscores@yelp.com along with a link to the sample feed zip file.
Yelp will validate and test the data until it is satisfactory.
Ship it!
Hosting the feed
Place your zip file in a directory. For example:
http://<your fileserver domain>/feed/latest/yelp_sf_healthscores.zip
To change or update the feed, replace the file.
Yelp will periodically pick up the file from the location you have specified.
Work at City Hall?
Do you work for a city that conducts hygiene grading and shares the data online? Your city can participate.
Send us an email at healthscores@yelp.com LIVES Data Specification
LIVES requires that data be presented in several CSV files consolidated in a single ZIP file. The required and optional files to include are: Required:
businesses.csv (format)
inspections.csv (format)
feed_info.csv (format)
Optional:
violations.csv (format)
legend.csv (format)
The remaining sections of this page detail each file's specific format. The following requirements apply to all submitted files:
All files in a LIVES feed must be saved as comma-delimited text.
The first line of each file must contain field names. Field names for each file are defined below under the ‘Files’ heading.
Field values may not contain tabs, carriage returns or new lines.
Field values that contain quotation marks or commas must be enclosed within quotes. This is consistent with the manner in which Microsoft Excel outputs comma-delimited (CSV) files. The following example demonstrates how a field value would appear in a comma-delimited file:
Original field value: Contains "quotes", commas and text
Field value in CSV file: "Contains ""quotes"", commas and text"
Field values must not contain HTML tags, comments, escape sequences, or anything else designed to break or confuse our computers.
Remove any extra spaces between fields or field names. Many parsers consider the spaces to be part of the value, which may cause errors.
Each line must end with a CRLF or LF linebreak character.
Files should be encoded in UTF-8 to support all Unicode characters. Files that include the Unicode byte-order mark (BOM) character are acceptable.
Files must be provided in a single .zip archive with flat hierarchy.
The businesses.csv file contains information about businesses. This file is required.
| Name | Type | Required | Description |
|---|---|---|---|
| business_id | string | Yes | Unique identifier for the business. For many cities, this may be the license number. |
| name | string | Yes | Common name of the business. |
| address | string | Yes | "Street address of the business. Example: 706 Mission St." |
| city | string | Yes | City of the business. This field must be included if the file contains businesses from multiple cities. |
| state | string | Yes | State or province for the business. In the U.S. this should be the two-letter code for the state. |
| postal_code | string | No | Zip code or other postal code. |
| latitude | number | No | "Latitude of the business. This field must be a valid WGS 84 latitude. Example: 37.7859547" |
| longitude | number | No | "Longitude of the business. This field must be a valid WGS 84 longitude. Example: -122.4024658" |
| phone_number | string | No | "Phone number for a business including country specific dialing information. Example: +14159083801" |
The inspections.csv file contains information about inspectors’ visits to businesses. This file is required.
| Name | Type | Required | Description |
|---|---|---|---|
| business_id | string | Yes | Unique identifier of the business for which this inspection was done. |
| date | date | Yes | Date of the inspection in YYYYMMDD format. |
| score | number | No* | Inspection score on a 0-100 scale. 100 is the highest score. * This column must always be present in inspections.csv. However, it can be safely left blank for inspection rows that don’t have an associated score (For example, some municipalities don’t associate a follow-up inspection with a score). * If scores are available for a business, there must be at least one inspection with a score provided. |
| result | string | No** | For cities that do not capture a score, this string represents the non-numeric result of the inspection. The string must be 4 characters or fewer. Examples: 'Pass' or 'Fail' ** This field is required if scores are unavailable. |
| description | string | No | Single line description containing details on the outcome of an inspection. Use of this field is only encouraged if no violations are provided. |
| type | string | No | String representing the type of inspection. Must be one of: initial, routine, followup, complaint |
The feed_info.csv file contains information about the feed itself. This file should only contain a single row. This file is required.
| Name | Type | Required | Description |
|---|---|---|---|
| feed_date | date | Yes | Date this feed was generated in YYYYMMDD format. |
| feed_version | string | Yes | Version of the LIVES specification used to generate this feed. Example: ‘2.0’ |
| municipality_name | string | Yes | Name of the municipality providing this feed. Examples: ‘San Francisco’ or ‘Multnomah County’ |
| municipality_url | string | Yes | URL of the publishing municipality’s website. |
| contact_email | string | Yes | Email address of the person to contact regarding invalid data in this feed. |
The violations.csv file contains information about specific violations. This file is optional.
| Name | Type | Required | Description |
|---|---|---|---|
| business_id | string | Yes | Unique identifier of the business for which this violation applies. |
| date | date | Yes | Date of violation in YYYYMMDD format. This should correspond with the related inspection. |
| code | string | No | Code for the violation. It is recommended that this be based on the FDA Food Code. However, municipalities can decide to use pre-existing codes for this field. |
| description | string | No | One line description of the violation. |
| critical | boolean | No | Describes whether the violation is critical (i.e., if it would cause the restaurant to fail their inspection). Must be one of: true, false |
The legend.csv file contains a mappings from score ranges to human-readable descriptions of those scores. Municipalities can use this file to communicate the way scores are traditionally presented. For example, 0-60 may map to ‘Fail’ or 95-100 may map to ‘A+’. The provided ranges in minimum_score and maximum_score must cover the entire 0-100 span without overlap. For scores at the edge of two ranges, the greater range will be used. For example, if 80-90 is a ‘B’ and 90-100 is an ‘A’, a score of 90 would be an ‘A’. This file is optional.
| Name | Type | Required | Description |
|---|---|---|---|
| minimum_score | number | Yes | Minimum score that can be classified with this description. |
| maximum_score | number | Yes | Maximum score that can be classified with this description. |
| description | string | Yes | Formatted version of the score in the format typically presented by the municipality. Examples: ‘A’ or ‘Pass’ |
This is version 2.0 of LIVES. It was last updated on August 10, 2015.