Documentation

 

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-reversegeo.api.smartystreets.com/lookup?auth-id=123&auth-token=abc

Here is a more granular examination of the example above:

URL ComponentsValuesNotes
SchemehttpsNOTE: Non-secure http requests are not supported.
Hostnameus-reversegeo.api.smartystreets.com
Path/lookup
Query String?auth-id=123&auth-token=abcAuthentication information, inputs, etc. Additional query string parameters are introduced in the next section.

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 method is supported by this API:

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

HTTP Request: Headers

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

HeaderDescriptionExample
HostThe 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-reversegeo.api.smartystreets.com
RefererThe Referer is required when a website 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 website 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)

NameTypeDefault ValueDescription
latitudedecimal(empty)Required. The latitude portion of the coordinate. The latitude must be specified as a decimal between -90.0 and 90.0.
longitudedecimal(empty)Required. The longitude portion of the coordinate. The longitude must be specified as a decimal between -180.0 and 180.0.
measurementstring(empty)Required.The unit of measurement for the distance values found in the results. The measurement must be specified in feet, miles, meters, or kilometers.
resultsinteger(empty)Required.The max number of results to include. The maximum number of results must be specified as an integer between 1 and 20.

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 CodeResponse and Explanation
401Unauthorized: The credentials were provided incorrectly or did not match any existing, active credentials.
402Payment Required: There is no active subscription for the account associated with the credentials submitted with the request.
400Bad Request (Malformed Payload): The request body was blank or otherwise malformed.
422Unprocessable Entity (Unsuitable Parameters): Returns errors describing what needs to be corrected.
429Too Many Requests: When using public website key authentication, we restrict the number of requests coming from a given source over too short of a time. If you use website key authentication, you can avoid this error by adding your IP address as an authorized host for the website key in question.
200OK (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-reversegeo.api.smartystreets.com/lookup?
			auth-id=YOUR+AUTH-ID+HERE&
			auth-token=YOUR+AUTH-TOKEN+HERE&
			latitude=40.202605&longitude=-111.621959&
			measurement=meters&results=2'
					

The above sample request yields the following JSON output:

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

HTTP Response Body: Output Field Definitions

Only non-blank fields will be returned.

Root

Field NameTypeDefinition
resultsarrayThe array of result objects. Each object contains the fields described below in the result section.

Result

Field NameTypeDefinition
latitudedecimalThe latitude value of this address.
longitudedecimalThe longitude value of this address.
licenseintThe license ID. See the table below for more details.
distancedecimalThe distance of this address to the input latitude/longitude values. The unit of measurement corresponds to the input measurement value.
streetvarchar(64)The street name of this address.
cityvarchar(64)The city name of this address.
statevarchar(2)The state abbreviation of this address.
zipcodevarchar(5)The 5-digit ZIP Code of this address.

Data Licenses

License IDLicense NameLicense Info
0SmartyStreetsResults with this license ID are provided with an open/unrestricted license. Attribution is optional.
1TigerTIGER/LineĀ® dataset from the US Census Bureau

SSL/TLS Information

Use Modern Security Software and Cipher Suites

Certificate Authority:
	AddTrust External CA Root
	Fingerprint: 02faf3e291435468607857694df5e45b68851868

Supported Protocols:
	TLS 1.2
	TLS 1.1 (No longer supported after Tuesday, January 21, 2020 at 9 AM Eastern Time)
	TLS 1.0 (No longer supported after Tuesday, January 21, 2020 at 9 AM Eastern Time)

Cipher Suites:
	TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256
	TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
	TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256
	TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA
	TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384
	TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA
	TLS_RSA_WITH_AES_128_GCM_SHA256
	TLS_RSA_WITH_AES_256_GCM_SHA384
	TLS_RSA_WITH_AES_128_CBC_SHA256
	TLS_RSA_WITH_AES_128_CBC_SHA
	TLS_RSA_WITH_AES_256_CBC_SHA256
	TLS_RSA_WITH_AES_256_CBC_SHA
This site uses cookies for analytics, personalized content, and ads. By continuing to browse this site, you agree to this use.
Consuming raw or undercooked cookie dough may increase your risk of foodborne illness.