Local Inspector Value-Entry Specification (LIVES)

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: [email protected]. 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 [email protected] 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 [email protected] 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.

Businesses

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"

Inspections

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

Feed Information

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.

Violation

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

Score Legend

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.