view  

The 3taps Data Commons

The Reference API

The 3taps Reference API provides information about the data sources, category groups, categories and locations available within the 3taps system. This information can be used by external systems to do things such as displaying a pick-list of available categories, translating location codes into location names, etc.

Caching Reference Data

External systems will often need to download and store a local cache of the reference data. To allow for this, the Reference API can tell the caller when a particular piece of information was last changed. The external system can then check the modification date to see if a piece of reference information has changed, and if so download the data again. This check can either be done periodically (eg, once per hour), or it can be done automatically each time the reference information is needed.

To see when a particular piece of reference data was last changed, make an HTTP HEAD request with the same URL as the data to be requested. The server will return a response with no body, but with a Last-Modified header that contains the date and time at which the given piece of information was last changed.

Data Sources

To obtain a list of data sources, make an HTTP GET request to the following URL:

http://reference.3taps.com/sources

The API call accepts the following parameter:

auth_token (required)

The authentication token used to ensure that you are authorized to make this API call.

Upon completion, this API call will return an HTTP status code of 200 (OK), a Content-Type of application/json, and the body of the response will be a JSON-encoded object with some combination of the following fields:

success

A boolean indicating whether or not the request succeeded.


Note that this is only provided for consistency with the other Reference API calls; errors are not possible for this particular call.


error

If the request was not successful, this will be a string describing what went wrong.

sources

An array of data sources. Each item in this array will be an object with the following entries:

code

The 3taps code for this data source.

name

The human-readable name for this data source.

Note that the list of data sources will be sorted alphabetically by name.

To see when the list of data sources was last updated, make an HTTP HEAD request to the same URL, supplying the same parameters. The returned response will have a Last-Modified header containing the date and time at which the data sources were last modified, in RFC 2822 format.

Category Groups

To obtain a list of category groups, make an HTTP GET request to the following URL:

http://reference.3taps.com/category_groups

The API call accepts the following parameter:

auth_token (required)

The authentication token used to ensure that you are authorized to make this API call.

Upon completion, this API call will return an HTTP status code of 200 (OK), a Content-Type of application/json, and the body of the response will be a JSON-encoded object with some combination of the following fields:

success

A boolean indicating whether or not the request succeeded.

error

If the request was not successful, this will be a string describing what went wrong.

category_groups

An array of category groups. Each item in this array will be an object with the following entries:

code

The 3taps code for this category group.

name

A human-readable name for this category group.

To see when the list of category groups was last updated, make an HTTP HEAD request to the same URL, supplying the same parameters. The returned response will have a Last-Modified header containing the date and time at which the category groups were last modified, in RFC 2822 format.

Categories

To obtain a list of categories, make an HTTP GET request to the following URL:

http://reference.3taps.com/categories

The API call accepts the following parameter:

auth_token (required)

The authentication token used to ensure that you are authorized to make this API call.

Upon completion, this API call will return an HTTP status code of 200 (OK), a Content-Type of application/json, and the body of the response will be a JSON-encoded object with some combination of the following fields:

success

A boolean indicating whether or not the request succeeded.

error

If the request was not successful, this will be a string describing what went wrong.

categories

An array of categories. Each item in this array will be an object with the following entries:

group_name

The name of the category group this category belongs to.

group_code

The 3taps code for the category group this category belongs to.

code

The 3taps code for this category.

name

A human-readable name for this category.

Note that the returned categories array will be sorted alphabetically by group name. Within each group, the individual categories are sorted according to the order in which they should appear in a pick-list. For example, the categories within the "Vehicles" group will be sorted like this:

Autos   
Parts   
Other

To see when the list of categories was last updated, make an HTTP HEAD request to the same URL, supplying the same parameters. The returned response will have a Last-Modified header containing the date and time at which the categories were last modified, in RFC 2822 format.

Locations

To obtain a list of locations, make an HTTP GET request to the following URL:

http://reference.3taps.com/locations

The API call accepts the following parameters:

auth_token (required)

The authentication token used to ensure that you are authorized to make this API call.

level (required)

The desired location level. The following location levels are currently supported:

country   
state   
metro   
region   
county   
city   
locality   
zipcode

Some or all of the locations at the given level will be returned. The following additional parameters can be used to filter the locations to return:

country (optional)

Only include locations that are completely or partly within the given country. The parameter's value must be a valid 3taps country code.

state (optional)

Only include locations that are completely or partly within the given state. The parameter's value must be a valid 3taps state code.

metro (optional)

Only include locations that are completely or partly within the given metro area. The parameter's value must be a valid 3taps metro area code.

region (optional)

Only include locations that are completely or partly within the given region. The parameter's value must be a valid 3taps region code.

county (optional)

Only include locations that are completely or partly within the given county. The parameter's value must be a valid 3taps county code.

city (optional)

Only include locations that are completely or partly within the given city. The parameter's value must be a valid 3taps city code.

locality (optional)

Only include locations that are completely or partly within the given locality. The parameter's value must be a valid 3taps locality code.

min_lat
min_long
max_lat
max_long (all optional)

If these parameters are supplied, only locations which are completely or partially enclosed by the given lat/long bounding box will be returned:

This can be useful for doing map visualisations where you only want to find locations that intersect with a particular area of the world.

Note that a caller would typically download the complete list of countries (by specifying the level=country parameter), and would then download lower-level locations filtered by the desired country, state, metro area, etc, as they are required. This avoids downloading too many locations at once.

Upon completion, this API call will return an HTTP status code of 200 (OK), a Content-Type of application/json, and the body of the response will be a JSON-encoded object with some combination of the following fields:

success

A boolean indicating whether or not the request succeeded.

error

If the request was not successful, this will be a string describing what went wrong.

locations

An array of matching locations. Each item in this array will be an object with the following entries:

code

The 3taps code for this location.

short_name

The short name for this location, without any higher-level context. For example, the locality of Chinatown in San Francisco will have a short name of Chinatown.

full_name

The full name for this location, including a context to distinguish it from other locations which may have the same name. For example, the locality of Chinatown in San Francisco will have a full name of Chinatown, San Francisco, CA.

Where there is no ambiguity, the location's full name will be the same as the short name.

bounds_min_lat
bounds_min_long
bounds_max_lat
bounds_max_long

The lat/long bounding box that completely encloses this location's outline.

Note that the returned list of locations will be sorted by full name.

To see when the list of locations was last updated, make an HTTP HEAD request to the same URL, supplying the same parameters. The returned response will have a Last-Modified header containing the date and time at which the locations were last modified, in RFC 2822 format. Note that the returned date/time is the date and time at which any location was last modified; the level and bounds filters are ignored for the HEAD request.

Location Lookups

The find the details of a single location based on its 3taps location code, you can make an HTTP GET request to the following URL:

http://reference.3taps.com/locations/lookup

The API call accepts the following parameters:

auth_token (required)

The authentication token used to ensure that you are authorized to make this API call.

code (required)

The 3taps location code for the desired location.

Upon completion, this API call will return an HTTP status code of 200 (OK), a Content-Type of application/json, and the body of the response will be a JSON-encoded object with some combination of the following fields:

success

A boolean indicating whether or not the request succeeded.

error

If the request was not successful, this will be a string describing what went wrong.

location

An object containing the details of the matching location. This object will have the following fields:

code

The 3taps code for this location.

level

The level of this location. This will be a string with one of the following values:

country   
state   
metro   
region   
county   
city   
locality   
zipcode

short_name

The short name for this location, without any higher-level context. For example, the locality of Chinatown in San Francisco will have a short name of Chinatown.

full_name

The full name for this location, including a context to distinguish it from other locations which may have the same name. For example, the locality of Chinatown in San Francisco will have a full name of Chinatown, San Francisco, CA.

Where there is no ambiguity, the location's full name will be the same as the short name.

bounds_min_lat
bounds_min_long
bounds_max_lat
bounds_max_long

The lat/long bounding box that completely encloses this location's outline.