VegGuide.org REST API

VegGuide currently supports a read-only REST API. This API allows you to retrieve information about entries, regions, and users using a well-defined set of URIs. Currently, all information is returned as JSON.

SSL

All REST API URIs may be accessed via http or https.

API Explorer

There is an API explorer app if you'd like to learn more about the API by playing with it.

Versioning

This document describes version 0.0.7 of the VegGuide REST API. This version number follows the Semantic Versioning Specification. Since the major version number is currently 0, the API is still in the experimental phase, and may change a fair bit before it is declared stable.

A new URI endpoint is considered a minor version change. Adding an additional key to an existing document is also a minor version change. Removing a key or changing an the type of an existing key in a document is a major version change. Removing a URI endpoint or changing it's document type entirely is a major version change.

Content Types

All responses from this REST API are valid JSON documents. However, rather than using a generic application/json Content-Type header, we use a content type that specifies the data in the response.

For example, information about an entry is returned with the content type application/vnd.vegguide.org-entry+json; charset=UTF-8; version=0.0.7. The first part of the content type tells you that the document contains information on a single entry. The remainder indicates the charset and version.

In the future, the minor and patch numbers of the version may change without warning. If we ever need to update the major version number, we will almost certainly honor the Accept header if it requests an older (major) version number.

Each document describes either a single resource or a collection of resources. Typically, these resources will be regions, entries, or users. Depending on the document type, a resource may in turn contain information about related resources. For example, a region resource may include information about the entries it contains, or an entry may contain information about the user who created it.

Core Data Structures

The follow data types appear in many responses, and the documentation will reference them rather than repeat their definitions over and over. Whenever a data structure includes a URI, that URI will contain the full URI, including scheme and hostname. The core data structures are always a JSON object with a set of well-defined keys and values.

Some structures include both English data and localized data. The English data should always be in the Latin-1 subset of Unicode. The localized data may be in any script. In most cases, you can figure out the language of the localized data by looking at the locale associated with the region. All strings are in UTF-8 encoding.

If a key's value would be null, an empty string, or an empty array, it is always omitted.

All datetimes are returned RFC3339 format. Datetimes are always in the UTC time zone.

Region

A region can be anything from a continent to a city. We also have some special regions like "Internet", "Airports", or a specific airport like "MSP - Twin Cities".

A region can contain entries, child regions, or in some rare cases, both. A region data structure contains the following keys:

Key name Type Description Always present?
name string The name of the region in English.
localized_name string The name of the region in the region's locale, if it has one.
is_country boolean Indicates whether or not the region is a country.
locale string A locale code like "en_CA" or "zh_TW". This is the locale for any localized data associated with the region's entries. Elements of the locale code are separated by underscores ("_").
time_zone string The name of the time zone associated with this region. This will be an IANA time zone name like "America/Chicago" or "Asia/Taipei".
entry_count integer (>= 0) The number of entries in the region. This only include entries which are not marked closed. Also note that this does not recurse into the child regions for this region. This may be 0.
uri URI The canonical URI for the region. This URI always returns the full region data structure for the given region.
entries_uri URI A URI which returns the list of entries for the region.
The following keys are only present when the data structure includes related data.
parent Region The region's parent region, if it has one. This is a single Region data structure without any related data. It may not be present if the region is a top-level region.
children array of Regions An array of child regions contained in this region. For example, the "USA" region contains the "Minnesota" and "New York" regions, among others. The child regions are themselves Region data structures, but they do not include any related data. This key may not be present if the region does not have any child regions.
comments array of Comments An array of comment data structures. Comments for a region typically contain some information about veg eating in the region. They may also contain references to other websites of interest for the region. See below for details on the Comment data structure. This key may not be present if the region does not have any comments.

Entry

An entry is a single place in the database, such as a restaurant or grocery.

Key name Type Description Always present?
name string The entry's name in English.
distance floating point number The entry's distance from a search location. This is only present when searching for entries near a specific location. There may be many digits after the decimal point, so client libraries should round this value as needed for display. This is always present for entries in geographical search results, and never present otherwise.
sortable_name string The entry's name in English, but with words like "A" and "The" removed. This is only done for English words.
localized_name string The name of the entry in the language of region's locale, if it has one.
short_description string A short description of the entry.
localized_short_description string A short description in the language of the region's locale.
long_description Formatted Text A longer description of the entry. This may include VegGuide wikitext markup.
localized_long_description Formatted Text A long description in the language of the region's locale. This may include VegGuide wikitext markup.
address1,
address2,
neighborhood,
city,
region,
postal_code,
country
string Address information for the entry. The region is the entry's state or province.
localized_address1,
localized_address2,
localized_neighborhood,
localized_city,
localized_region,
postal_code
string Localized address information for the entry.
directions string Directions to the location of the entry.
phone string A phone number for the entry. This will not be in any specific format, and may not always include a country prefix.
website URI A website for the entry. This may be a Facebook page in some cases.
veg_level,
veg_level_description
integer,
string

How veg-friendly the entry is, from 0-5. The levels are:

  • 0 - Not Veg-Friendly
  • 1 - Vegetarian-Friendly
  • 2 - Vegan-Friendly
  • 3 - Vegetarian (But Not Vegan-Friendly)
  • 4 - Vegetarian
  • 5 - Vegan

Level 0 and level 3 are both very rare in our database.

price_range string

A description of the entry's price range. Currently these can be:

  • $ - inexpensive
  • $$ - average
  • $$$ - expensive
hours array of objects

This key describes the entry's hours of operations. It consists of an array of objects. Each objects has two keys, days and hours. The days key contains something like "Mon" or "Mon - Fri". The hours key is itself an array of strings. Each element of the array contains a time range. Some places close between lunch and dinner, and these have two elements in the array. There is an example at the end of this table.

allows_smoking boolean or null Indicates whether or not smoking is allows at this place. Note that this field can be null, which means that we do not know whether or not smoking is allowed.
is_wheelchair_accessible boolean or null A boolean indicating whether or not this entry is wheelchair-accessible. This field can be null, which means that we do not know whether or not it is accessible.
accepts_reservations boolean or null A boolean indicating whether or not this entry accepts reservations. This field can be null, which means that we do not know whether or not it accepts reservations.
is_cash_only boolean Indicates whether or not this entry only accepts cash as payment.
payment_options array of strings An array of strings with payment options like "Check" or "Visa". These are always returned in alphabetically sorted order.
creation_datetime,
last_modified_datetime
datetime When an entry is first created, these two datetimes are the same.
close_date date This is set when an entry is no longer open. This is just a date without a time in YYYY-MM-DD format, something like "2012-07-09".
rating_count integer (>= 0) The number of ratings for this entry. This may be 0.
weighted_rating decimal The weighted rating for the entry. This will be a decimal number from 1 to 5. This will not be present if no one has rated the entry yet.
categories array of strings

An array of category names for the entry. Every entry has at least one category. The current list of categories is:

  • Restaurant
  • Coffee/Tea/Juice
  • Bar
  • Food Court or Street Vendor
  • Grocery/Bakery/Deli
  • Caterer
  • General Store
  • Organization
  • Hotel/B&B
  • Other

For entries with more than one category, they will be ordered per the list above. This is intended to reflect the relative importance of each category. For example, many entries on the site are in both the "Restaurant" and "Caterer" category, but the former is more interesting (to most users) than the latter.

cuisines array of strings

An array of cuisines names for the entry. These are things like "Chinese", "Indian", or "Pizza". This only applies to some categories of entry, and not every entry has this key set. These are always returned in alphabetically sorted order.

tags array of strings

An array of tags for the entry. These are things like "Large Group-Friendly" or "Romantic". These are returned in alphabetically sorted order.

images array of Images An array of Image data structures for the entry. Each image will include four sizes. The first three are limited to 120x120, 250x250, and 400x620 respectively. The last will be the image that was originally uploaded, which can be any size, and may potentially be quite large.
user User A minimal User data structure (uri and name only) for the creator of this entry. This data structure does not include related data.
uri URI The canonical URI for the entry. This URI always returns the full entry data structure for the given entry.
reviews_uri URI A URI which returns the reviews and ratings for this entry.
The following keys are only present when the data structure includes related data.
region Region A Region data structure for the creator of this entry. This data structure does not include related data. ✔ (when related data is included)

Here is an example of the hours data structure:

[
    {
        days  => 'Mon - Fri',
        hours => ['10:30am - 2pm', '5pm - 10pm']
    },
    {
        days  => 'Sat - Sun',
        hours => ['closed']
    }
]

User

Key name Type Description Always present?
name string The user's username.
bio Formatted Text Biographical information about the user.
veg_level,
veg_level_description
integer,
string

How vegetarian the user is, from 0-4. The levels are:

  • 0 - not telling
  • 1 - not vegetarian
  • 2 - mostly vegetarian, but not always
  • 3 - vegetarian
  • 4 - vegan
website URI The website for the user.
image Image An Image data structure for the user. This will include two sizes of image. The smaller of the two is limited to 40x40, and the larger to 100x100. The image data structure will not include user information.
uri URI The canonical URI for the user. This URI always returns the full user data structure for the given user.

User data structures come in two variations. In some cases, an end point only provides the uri and name keys for a user. The documentation calls this a minimal User data structure, as opposed to a complete User data structure.

Comment

Both region comments and entry reviews are returned with essentially the same data structure, though reviews have some additional data.

Note that an entry review may contain just a body, just a rating, or both.

Key name Type Description Always present?
body Formatted Text The comment body as a Formatted Text data structure.
user User A complete User data structure for the author of the comment. This data structure does not include related data.
last_modified_datetime datetime When this comment was created or most recently updated.
rating integer (1-5) A rating from 1 to 5, where 1 is terrible and 5 is excellent. This is only present for entry reviews, not region comments.

Image

An image is a single picture, usually available in multiple sizes. The image data may include a caption, as well as information about the user who uploaded the image.

Key name Type Description Always present?
mime_type string This will be one of image/gif, image/jpeg, or image/png.
caption string A caption for the image.
files array of Image Files This is an array of image file structures. Each structure provides information about an image file with a specified size. The array is always sorted by size. The possible dimensions for each image file depends on whether this is a user or entry image.
user User A minimal User data structure (uri and name only) for the user who uploaded this image. This data structure does not include related data.

Image File

This data structure contains information about a specific file for an image.

Key name Type Description Always present?
uri URI The URI for this image file.
height positive integer The height of the image.
width positive integer The width of the image.

Formatted Text

Some fields contain a type of wikitext which is rendered as HTML on the website. These fields are returned as objects where the attribute names are a MIME type and the attribute values are the text in that format. Currently, this data structure return two MIME types, text/html, and text/vnd.vegguide.org-wikitext. The wikitext format VegGuide uses is described on the help page.

    {
        'text/html':                      '<p>Blah blah blah</p>',
        'text/vnd.vegguide.org-wikitext': 'Blah blah blah'
    }

In the future, the site will use Markdown internally, and the existing wikitext format will go away. You are encouraged to use the HTML representation if you can.

Entry Points

The VegGuide REST API defines several well known entry points. These URIs are guaranteed to exist, and their responses will generally contain links to other site URIs.

Many of the URIs that the site offers include a numeric id, for example /region/13. You are strongly encouraged not to rely on the stability of these numbers. Instead, use one of the defined entry points to find items of interest for your applications.

Top-Level

  • URI: http://www.vegguide.org/
  • Type: application/vnd.vegguide.org-regions+json

The top-level URI returns a document enumerating the top-level regions.

The structure of the document is as follows:

{
    "regions": {
        "primary":   [ ... ],
        "secondary": [ ... ]
    }
}

The primary and secondary keys contain an array of Region data structures with related data. The primary regions are continents and oceanic areas. The secondary regions are currently just "Internet" and "Airports".

Geographical Searches

There are two different entry point URIs for geographical searches. You can search by address or by latitude and longitude. Both URIs return the same response.

  • Address URI: http://www.vegguide.org/search/by-address/{address}
  • Lat/Long URI: http://www.vegguide.org/search/by-lat-long/{latitude},{longitude}
  • Type: application/vnd.vegguide.org-entries+json

These searches accept the following query parameters:

Key name Type Default value Description
distance positive number 5 The search "radius" in miles or kilometers. This isn't really a radius. Instead, the search is really for a square where each side of the square is distance units long, and each side is distance / 2 units away from the center point.
unit enum see description This can be either mile or km. If the search is for an address in the US, this defaults to mile, otherwise it defaults to km.
limit positive integer 50 The maximum number of entries to return. This cannot be greater than 100.
page positive integer 1 If there are more than limit entries in the search, this parameter lets you fetch subsequent pages of results.

This document returns the result of a search around a specific address or latitude and longitude.

{
    "uri":           "http://...",
    "entry_count":   123,
    "distance_unit": "mile",
    "entries":       [ ... ],
    "region":        { ... },
    "filters"        [ ... ]
}

The entries key contains an array of Entry data structures without related data. The entry data structures will include a distance key. The regions key contains the region associated with the nearest entry. This is a Region data structure without related data.

The distance_unit key is always "mile" or "km".

The filters key is only included for search with filters. It is an array of strings where each string describes one of the filters as a sentence fragment. For example, when you filter for entries which are at least vegetarian or vegan, the description is "which are at least Vegetarian". The intent is that you can use these fragments in a sentence like "you searched for entries ...".

If you search by address and the address does not resolve to a latitude and longitude, we return a 404 Not Found response.

Filtering Search Results

All search URIs support various filters. These are applied by appending filters to the URI as path elements after the path element /filter. For example, the path for a search address would look something like:

/search/by-address/{address}/filter/key1=foo;key2=bar

Multiple filters should be separated by a semi-colon (;) as in the example above. With some filters, you may repeat the key with different values, others can only be specified once.

The following filters are currently available:

Key name Type Repeatable? Description
category_id enum yes

This filter limits the search so it only returns entries in the specified categories. Categories are identified by an integer id, as follows:

  • 1: Restaurant
  • 2: Grocery/Bakery/Deli
  • 3: Caterer
  • 4: Organization
  • 5: Coffee/Tea/Juice
  • 6: Bar
  • 7: General Store
  • 8: Other
  • 9: Food Court or Street Vendor
  • 10: Hotel/B&B
veg_level enum no

This filter specifies the minimum veg-friendliness for search results. The valid values are:

  • 5: Vegan
  • 4: Vegetarian
  • 3: Vegetarian (But Not Vegan-Friendly)
  • 2: Vegan-Friendly
  • 1: Vegetarian-Friendly

Other URIs

These URIs will show up in other data structures, so understanding their document structures is important when coding to this API. All of these URIs include a numeric id but you are encouraged to not rely on these numbers remaining stable.

Region

  • URI: http://www.vegguide.org/region/{id}
  • Type: application/vnd.vegguide.org-region+json

Returns a Region data structure. These URIs show up in any response that includes region URIs, including the top level response, a region's list of child regions, and an entry's link to its containing region.

Region Entries

  • URI: http://www.vegguide.org/region/{id}/entries
  • Type: application/vnd.vegguide.org-entries+json

Returns an array of Entry data structures for the region. This document only includes entries that are not marked as closed.

Entry

  • URI: http://www.vegguide.org/entry/{id}
  • Type: application/vnd.vegguide.org-entry+json

Returns a Entry data structure. These URIs show up in any response that includes entry URIs, such as a region's entries list or search results.

Entry Reviews

  • URI: http://www.vegguide.org/entry/{id}/reviews
  • Type: application/vnd.vegguide.org-entry-reviews+json

Returns an array of Comment data structures. These URIs show up in any response that includes entry review URIs, such as a entry's reviews list.

User

  • URI: http://www.vegguide.org/user/{id}
  • Type: application/vnd.vegguide.org-user+json

Returns a complete User data structure. These URIs show up in any response that includes user URIs, such as an entry or image data structure.

Error Responses

Error responses are accompanied by a JSON document body describing the error except for errors in the 5xx range, which typically mean something went wrong server side. The content type for errors is always application/vnd.vegguide.org-error+json

Error bodies are a JSON object containing one key, error. The value for this key is a user-readable message describing the error.

HTTP Access Control (CORS)

All responses from the rest API include an Access-Control-Allow-Origin: * header.

Release History

0.0.7 - February 17, 2013

  • Added documentation for search filters.

0.0.6 - February 3, 2013

  • Added support for SSL but forgot to document it.

0.0.5 - December 29, 2012

  • Added the payment_options key to the Entry data structure.

0.0.4 - December 9, 2012

  • All REST responses now include an Access-Control-Allow-Origin: * header to allow cross-site requests.

0.0.3 - October 14, 2012

  • The Entry structures for geographical searches now return the distance as an unrounded floating point number. The search response itself now includes a distance_unit key ("mile" or "km"). Client libraries should round the distance as needed for display.

0.0.2 - October 6, 2012

  • Some REST end points have been changed to only return partial User data, just the name and uri keys. This was changed for search results, entry listings, and entry images. The user end point and entry review end points still return the complete User data structure.
  • Lat/long searches always returned results based on miles, even though the docs said that miles are only used for locations inside the USA. This has been fixed.

0.0.1 - September 1, 2012

First release upon an unsuspecting world.