view  

The 3taps Data Commons

The Geolocator API

The 3taps Geolocator API allows callers to identify the 3taps location(s) associated with a given set of lat/long coordinates.

How the 3taps Geolocator Works

Latitude and longitude coordinates identify points on the surface of the Earth. A given coordinate can match up against any number of locations. For example, the coordinate latitude=37.863434, longitude=-122.578722 sits within the following 3taps locations:

Level Name 3taps Code
Country United States USA
State California USA-CA
Metro Area San Francisco USA-SFO
Region North Bay USA-SFO-NOR
County Marin USA-CA-MAN
City Sausalito USA-SFO-SAU
ZIP code 94965 USA-94965

Because this coordinate defines an exact position on the Earth's surface, a lat/long coordinate by itself does not tell you which location that point was supposed to represent. It may be that this coordinate is supposed to represent the San Francisco metro area; all those lower-level locations are false positives -- that is, locations that happen to match the given point but weren't supposed to be part of the desired location.

To allow for this, the 3taps Geolocator allows you to specify how precisely you want the location to be calculated. There are two ways of doing this: by specifying an accuracy value, or by supplying a desired bounds for the location. let's take a closer look at these two concepts.

Accuracy

Where you can supply it, accuracy is by far the easiest way of filtering out unwanted locations from the geolocator results. The accuracy value is a simple number indicating which location levels you want to have included in the results:

1 = coordinate is accurate only to the country level.
2 = coordinate is accurate only to the state level.
3 = coordinate is accurate only to the metro area level.
4 = coordinate is accurate only to the region level.
5 = coordinate is accurate only to the county level.
6 = coordinate is accurate only to the city level.
7 = coordinate is accurate only to the locality level.
8 = coordinate is accurate to at least the ZIP code level.

Bounds

Unfortunately, there are situations where you don't know the accuracy value. For example, when using version 3 of the Google Maps Geocoding API to convert a textual location into a lat/long coordinate, you don't have any way of knowing the accuracy of the returned lat/long coordinate. Instead, you are given a bounding box that surrounds the matched feature. For example:

This bounding box is returned as a series of four numbers, representing the minimum and maximum latitude and longitude values, like this:

These four numbers can be passed directly to the 3taps Geolocator API to filter out unwanted locations from the results.

Using the 3taps Geolocator API

To calculate the 3taps locations for a single lat/long coordinate, make an HTTP GET request to the following URL:

http://geolocator.3taps.com/reverse

Technically speaking, the process of converting a lat/long coordinate into a location is called reverse geocoding. This explains the /reverse part of the URL.


The following parameters are required by this API call:

latitude

The latitude of the desired coordinate, as a floating-point number.

longitude

The longitude of the desired coordinate, as a floating-point number.

To filter the geolocation results by an accuracy value, use the following additional parameter:

accuracy

An integer indicating the accuracy of the lat/long coordinate, if known. This value is interpreted as follows:

0 = unknown.
1 = coordinate is accurate only to the country level.
2 = coordinate is accurate only to the state level.
3 = coordinate is accurate only to the metro area level.
4 = coordinate is accurate only to the region level.
5 = coordinate is accurate only to the county level.
6 = coordinate is accurate only to the city level.
7 = coordinate is accurate only to the locality level.
8 = coordinate is accurate to at least the ZIP code level.

To use a bounding box to filter the geolocation results, the following additional parameters should be supplied:

bounds_min_lat

The minimum latitude for the bounding box.

bounds_min_long

The minimum longitude for the bounding box.

bounds_max_lat

The maximum latitude for the bounding box.

bounds_max_long

The maximum longitude for the bounding box.

Upon completion, the Geolocator API will send back a response with a Content-Type of application/json, and the body of the response will be a JSON-formatted object with the following fields:

success

A boolean indicating whether or not the reverse geocoding attempt was successful.

error

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

country

The 3taps location code for the matching country, if any.

state

The 3taps location code for the matching state, if any.

metro

The 3taps location code for the matching metro area, if any.

region

The 3taps location code for the matching region, if any.

county

The 3taps location code for the matching county, if any.

city

The 3taps location code for the matching city, if any.

locality

The 3taps location code for the matching locality, if any.

zipcode

The 3taps location code for the matching ZIP code, if any.

Note that the location field will only be included in the returned JSON object if (a) that location exists and encloses the given lat/long coordinate, and (b) the location was not filtered out by the supplied accuracy or bounds. Otherwise, the field will be missing from the returned JSON object.

Batch Reverse Geocoding

If you have a number of lat/long coordinates that need to be reverse geocoded, you can make use of the following API call:

http://geolocator.3taps.com/batch_reverse

The batch_reverse API call requires a coords parameter to be supplied. There are three ways you can supply this parameter:

  • As a URL-encoded parameter to an HTTP GET request. In this case, the request's Content-Type should be set to application/x-www-form-urlencoded.

  • As a form-encoded parameter within the body of an HTTP POST request. In this case, the request's Content-Type should be set to multipart/form-data.

  • As raw JSON data, supplied in the body of the request. In this case, the request's Content-Type should be set to application/json.

When supplied using form-encoding or URL-encoding, the coords parameter should be a string holding JSON-formatted data containing the coordinates to be processed. For example:

coords=[{"latitude" : 37.711, "longitude" : -122.399, "accuracy"}, ...]

When supplying the coordinates as raw JSON data, the body of the request should be a JSON object with a single field, coords, that holds the coordinates to be processed. For example:

 {"coords" : [{"latitude" : 37.711, "longitude" : -122.399, "accuracy"}, ... ] }

However it is supplied, the coords value should be an array of coordinates to reverse geocode. Each entry in this array should be an object with at least the following fields:

latitude

The latitude of the desired coordinate, as a floating-point number.

longitude

The longitude of the desired coordinate, as a floating-point number.

To filter the geolocation results by an accuracy value, the following field should be supplied:

accuracy

An integer indicating the accuracy of the lat/long coordinate, if known. This value is interpreted as follows:

0 = unknown.
1 = coordinate is accurate only to the country level.
2 = coordinate is accurate only to the state level.
3 = coordinate is accurate only to the metro area level.
4 = coordinate is accurate only to the region level.
5 = coordinate is accurate only to the county level.
6 = coordinate is accurate only to the city level.
7 = coordinate is accurate only to the locality level.
8 = coordinate is accurate to at least the ZIP code level.

To use a bounding box to filter the geolocation results, the following additional parameters should be supplied:

bounds_min_lat

The minimum latitude for the bounding box.

bounds_min_long

The minimum longitude for the bounding box.

bounds_max_lat

The maximum latitude for the bounding box.

bounds_max_long

The maximum longitude for the bounding box.

Upon completion, the Geolocator API will send back a response with a Content-Type of application/json, and the body of the response will be a JSON-formatted array containing an entry for each of the supplied coordinates. Each array entry will be an object with some combination of the following fields:

success

A boolean indicating whether or not the reverse geocoding attempt was successful for this coordinate.

error

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

country

The 3taps location code for the matching country, if any.

state

The 3taps location code for the matching state, if any.

metro

The 3taps location code for the matching metro area, if any.

region

The 3taps location code for the matching region, if any.

county

The 3taps location code for the matching county, if any.

city

The 3taps location code for the matching city, if any.

locality

The 3taps location code for the matching locality, if any.

zipcode

The 3taps location code for the matching ZIP code, if any.

Note that the location field will only be included in the returned JSON object if (a) that location exists and encloses the given lat/long coordinate, and (b) the location was not filtered out by the supplied accuracy or bounds. Otherwise, the field will be missing from the object returned for that coordinate.