US Reverse Geocoding API - Reverse geocoding made easy

This page describes how to discover the closest street addresses to a latitude/longitude coordinate, a process called "reverse geocoding".

Contents

1. HTTP request
   1. URL composition
   2. Request methods
   3. Input fields
   4. Headers
2. HTTP response
   1. Status codes and results
   2. Output field definitions
3. Supplementary materials
   1. SSL/TLS information

HTTP request: URL composition

Proper URL construction is required for all API requests. Here is an example URL:

https://us-reverse-geo.api.smarty.com/lookup?auth-id=123&auth-token=abc

Here is a more granular examination of the example above:

URL components	Values	Notes
Scheme	https	NOTE: Non-secure http requests are not supported.
Hostname	us-reverse-geo.api.smarty.com
Path	/lookup
Query string	?auth-id=123&auth-token=abc	Authentication information, inputs, etc. Additional query string parameters are introduced in the next section. Note: When utilizing any of our APIs, the license parameter is optional. See License Selection for guidance.

For additional information about URLs, please read our article about URL components.

HTTP request: Supported methods/verbs

HTTP requests can be categorized according to their HTTP method. Most HTTP requests are defined using the GET method. We call these "get requests." Other common methods are PUT, POST, and DELETE.

The following methods are supported by this API:

• GET (for sending a single input)
• OPTIONS (for "pre-flight" cross-domain requests)

Note: When calling any of our APIs using embedded key authentication, only the HTTP GET method is allowed.

HTTP request: Headers

You must include the following required HTTP headers in all requests:

Header	Description	Example
Host	The Host request header field specifies the internet host and port number of the resource being requested. Note: Most HTTP clients such as the browser, or programming language HTTP libraries will add this header automatically.	Host: us-reverse-geo.api.smarty.com
Referer	The Referer is required when an embedded key is used for authentication. Its value is in the form of a URL, where the host component must match a host value assigned to your embedded key. Note: Some HTTP clients such as a browser, or programming language HTTP libraries will add this header automatically. However some interfaces such as cURL do not, so you may need to add it manually.	Referer: https://mycoolwebsite.com

Input Fields (Query String Parameters)

Name	Type	Default value	Description
latitude	decimal	(empty)	Required. The latitude portion of the coordinate. The latitude must be specified as a decimal between -90.0 and 90.0.
longitude	decimal	(empty)	Required. The longitude portion of the coordinate. The longitude must be specified as a decimal between -180.0 and 180.0.
source	string	postal	Include results from alternate data sources. Allowed values are: all — will include non-postal addresses in the results postal — will limit the results to postal addresses only If this parameter is used, an additional field named source will be returned for each result.

Please note that all query string parameter values must be url-encoded (spaces become + or %20, for example) to ensure that the data is transferred correctly. A common mistake we see is a non-encoded pound sign (#) like in an apartment number (# 409). This character, when properly encoded in a URL, becomes %23. When not encoded this character functions as the fragment identifier, which is ignored by our API servers.

HTTP response: Status codes and results

Responses will have a status header with a numeric value. This value is what you should check for when writing code to parse the response. The only response body that should be read and parsed is a 200 response.

Status code	Response and explanation
401	Unauthorized: The credentials were provided incorrectly or did not match any existing, active credentials.
402	Payment Required: There is no active subscription for the account associated with the credentials submitted with the request.
400	Bad request (malformed payload): The request body was blank or otherwise malformed.
422	Unprocessable entity (unsuitable parameters): Returns errors describing what needs to be corrected.
429	Too many requests: When using public embedded key authentication, we restrict the number of requests coming from a given source over too short of a time. If you use embedded key authentication, you can avoid this error by adding your IP address as an authorized host for the embedded key in question.
200	OK (success!): The response body is a JSON object containing metadata about the results and zero or more addresses derived from the input provided with the request. See the example below for details.

HTTP response body

Rather than writing your own code to parse the JSON response, we recommend using a tried and tested JSON parser that is specific for your programming language. There is a very comprehensive list of such tools (as well as the complete JSON specification) at json.org.

NOTE: Any returned fields that are not defined within this document should be considered experimental and may be changed or discontinued at any time without notice.

curl -v 'https://us-reverse-geo.api.smarty.com/lookup?
	auth-id=YOUR+AUTH-ID+HERE&
	auth-token=YOUR+AUTH-TOKEN+HERE&
	latitude=40.202605&longitude=-111.621959'

The above sample request yields the following JSON output:

{
	"results": [
		{
			"coordinate": {
				"latitude": 40.202583,
				"longitude": -111.62196,
				"accuracy": "Rooftop",
				"license": 1
			},
			"distance": 2.7207432,
			"address": {
				"street": "2335 S State St",
				"city": "Provo",
				"state_abbreviation": "UT",
				"zipcode": "84606"
			}
		},
		{
			"coordinate": {
				"latitude": 40.20283,
				"longitude": -111.62167,
				"accuracy": "Zip9",
				"license": 0
			},
			"distance": 34.95276,
			"address": {
				"street": "2324 Mountain View Pkwy",
				"city": "Provo",
				"state_abbreviation": "UT",
				"zipcode": "84606"
			}
		}
	]
}

HTTP response body: Output field definitions

Only non-blank fields will be returned.

Root

Field name	Type	Definition
results	array	The array of result objects. Each object contains the fields described below in the result section.

Result

Field name	Type	Definition
distance	decimal	The distance in meters of this address to the input latitude/longitude values, expressed in decimal degrees.
address	[Object]	See Address table below.
coordinate	[Object]	See Coordinate table below.

Address

Field name	Type	Definition
street	varchar(64)	The street name of this address.
city	varchar(64)	The city name of this address.
state_abbreviation	varchar(2)	The state abbreviation of this address.
zipcode	varchar(5)	The 5-digit ZIP Code of this address.
source	varchar(6)	This field is only returned if the request contained the source parameter. When it is returned, it indicates the data source for this address. postal — the address is deliverable by the USPS other — the address was obtained from an alternate source (non-postal)

Coordinate

Field name	Type	Definition
latitude	decimal	The latitude value of this address.
longitude	decimal	The longitude value of this address.
accuracy	varchar(18)	Indicates the accuracy of the latitude and longitude values. Unknown — Coordinates not known. Reasons could include: lat/lon coordinates not available. Zip5 — Accurate to a 5-digit ZIP Code level (least accurate) Zip6 — Accurate to a 6-digit ZIP Code level Zip7 — Accurate to a 7-digit ZIP Code level Zip8 — Accurate to an 8-digit ZIP Code level Zip9 — Accurate to a 9-digit ZIP Code level Parcel — Accurate to the centroid of a property parcel. Rooftop — Accurate to the rooftop of a structure for this address. Note: Concerning addresses for which the ZIP9 accuracy is not available, the ZIP# accuracy is interpolated based on neighboring addresses. Thus, ZIP7 is an average of all the lat/long coordinates of nearby ZIP Codes that share those first 7 digits.
license	int	The license ID for the geographic coordinate returned. See the licensing table below for more details.

Geographic coordinate data licenses

ID	Name	Description
0	Smarty	Results with this coordinate license are provided with an open/unrestricted license. Attribution is optional.
1	Smarty proprietary	Smarty hereby grants a limited, worldwide, non-exclusive, non-transferable (except as authorized herein), revocable license to use this geocoding coordinate consisting of latitude and longitude values and associated metadata for internal business use purposes only and for the duration of the term stated for the online subscription.

SSL/TLS information

Use modern security software and cipher suites