US Reverse Geocoding API - reference

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:

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:

Input fields (Query string parameters)

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 serves as the fragment identifier, which our API servers ignore.

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.

HTTP response body

Rather than writing your own code to parse the JSON response, we recommend using a tried and tested JSON parser that’s specific to 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": [
		{
			"address": {
				"street": "2335 S State St",
				"city": "Provo",
				"state_abbreviation": "UT",
				"zipcode": "84606",
				"smarty_key": "1649988050"
			},
			"coordinate": {
				"latitude": 40.202583,
				"longitude": -111.621964,
				"license": 1,
				"accuracy": "Rooftop"
			},
			"distance": 2.626235
		},
		{
			"address": {
				"street": "2324 Mountain View Pkwy",
				"city": "Provo",
				"state_abbreviation": "UT",
				"zipcode": "84606",
				"smarty_key": "629428386"
			},
			"coordinate": {
				"latitude": 40.20314,
				"longitude": -111.622162,
				"license": 1,
				"accuracy": "Rooftop"
			},
			"distance": 61.907761
		},
		{
			"address": {
				"street": "2333 Tennessee Ave",
				"city": "Provo",
				"state_abbreviation": "UT",
				"zipcode": "84606",
				"smarty_key": "1319793564"
			},
			"coordinate": {
				"latitude": 40.202518,
				"longitude": -111.621063,
				"license": 1,
				"accuracy": "Rooftop"
			},
			"distance": 76.43438
		},
		{
			"address": {
				"street": "2272 Mountain View Pkwy",
				"city": "Provo",
				"state_abbreviation": "UT",
				"zipcode": "84606",
				"smarty_key": "371916805"
			},
			"coordinate": {
				"latitude": 40.203278,
				"longitude": -111.621552,
				"license": 1,
				"accuracy": "Rooftop"
			},
			"distance": 82.174355
		},
		{
			"address": {
				"street": "2097 Ironton Blvd",
				"city": "Provo",
				"state_abbreviation": "UT",
				"zipcode": "84606",
				"smarty_key": "1606973392"
			},
			"coordinate": {
				"latitude": 40.201946,
				"longitude": -111.622475,
				"license": 1,
				"accuracy": "Rooftop"
			},
			"distance": 85.59359
		},
		{
			"address": {
				"street": "2097 Billings Ave",
				"city": "Provo",
				"state_abbreviation": "UT",
				"zipcode": "84606",
				"smarty_key": "1606973392"
			},	
			"coordinate": {
				"latitude": 40.201946,
				"longitude": -111.622475,
				"license": 1,
				"accuracy": "Rooftop"
			},
			"distance": 85.59359
		},
		{
			"address": {
				"street": "2070 Arizona Ave",
				"city": "Provo",
				"state_abbreviation": "UT",
				"zipcode": "84606",
				"smarty_key": "1815382140"
			},
			"coordinate": {
				"latitude": 40.203026,
				"longitude": -111.62281,
				"license": 1,
				"accuracy": "Parcel"
			},
			"distance": 86.275002
		},
		{
			"address": {
				"street": "2342 Tennessee Ave",
				"city": "Provo",
				"state_abbreviation": "UT",
				"zipcode": "84606",
				"smarty_key": "854839548"
			},
			"coordinate": {
				"latitude": 40.202034,
				"longitude": -111.621262,
				"license": 1,
				"accuracy": "Rooftop"
			},
			"distance": 86.74633
		},
		{
			"address": {
				"street": "2345 Tennessee Ave",
				"city": "Provo",
				"state_abbreviation": "UT",
				"zipcode": "84606",
				"smarty_key": "413612042"
			},
			"coordinate": {
				"latitude": 40.202354,
				"longitude": -111.620903,
				"license": 1,
				"accuracy": "Rooftop"
			},
			"distance": 93.696243
		},
		{
			"address": {
				"street": "2315 S State St",
				"city": "Provo",
				"state_abbreviation": "UT",
				"zipcode": "84606",
				"smarty_key": "1015965304"
			},
			"coordinate": {
				"latitude": 40.203106,
				"longitude": -111.622871,
				"license": 1,
				"accuracy": "Rooftop"
			},
			"distance": 95.567581
		}
	]
}

HTTP response body: Output field definitions

Only non-blank fields will be returned.

Root

Result

Address

Coordinate

Geographic coordinate data licenses

SSL/TLS information

Use modern security software and cipher suites