US Address Enrichment API

This page describes how to retrieve data from various different datasets using the Smarty US Address Enrichment API.


  1. HTTP Request
    1. URL Composition
    2. Request Methods
    3. Headers
  2. HTTP Response
    1. Results
  3. Supplementary Materials
    1. SSL/TLS Information
    2. Try the Address Enrichment API Demo

HTTP Request: URL Composition

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

Here is a more granular examination of the example above:

URL Components Values Notes
Scheme https NOTE: Non-secure http requests are not supported
Path /lookup
Smarty Key /1000000 The unique id associated with the address you are looking for
Dataset /property The specific type of data you need
Data-Subset /principal
The specific subset of the dataset you need
Query String ?auth-id=12345&auth-token=abcdef Authentication information

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

HTTP Request: Supported Methods

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)

HTTP Request: Headers

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

Header Description Example
Content-Type The purpose of the Content-Type field is to describe the data contained in the body fully enough that the receiving user agent can pick an appropriate agent or mechanism to present the data to the user, or otherwise deal with the data in an appropriate manner. Content-Type: application/json

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.
429 Too Many Requests: We restrict the number of requests coming from a given source over too short of a time.
413 Request Entity Too Large: The request body was larger than 64 Kilobytes.
200 OK (success!): The response body is a JSON object containing metadata about the results and zero or more extracted addresses from the input provided with the request. See the annotated example below for details.

Example Response - Property/Principal Dataset

		"smarty-key": "4888552154",
		"data-set-name": "property",
		"data-subset-name": "principal",
		"attributes": {
			"1st_floor_sqft": "2302",
			"2nd_floor_sqft": "0",
			"acres": "0.3289945",
			"address_info_privacy": "",
			"air_conditioner": "yes",
			"arbor_pergola": "unknown",
			"assessed_improvement_percent": "0.00",
			"assessed_improvement_value": "0",
			"assessed_land_value": "0",
			"assessed_value": "399960",
			"assessor_last_update": "2023-01-05",
			"assessor_taxroll_update": "2022-01-01",
			"attic_area": "405",

Example Response - Property/Financial Dataset

		"smarty-key": "9856148841",
		"data-set-name": "property",
		"data-subset-name": "financial",
		"attributes": {
			"assessor_taxroll_update": "2022-01-01",
			"attic_area": "405",
			"recorder": [
					"recording_date": "2022-01-01",
					"instrument_date": "2022-01-01",
					"sale_price": "1",
					"recording_date": "2023-01-01",
					"instrument_date": "2023-01-01",
					"sale_price": "2",

Basic Use Cases

HTTP GET - SmartyKey Valid - Property Data Exists

Precondition SmartyKey is valid.
Property data exists.
Result All results for specific smarty-key returned.

HTTP GET - SmartyKey Not Valid

Precondition SmartyKey does not exist.
Result Empty results returned.

HTTP GET - SmartKey Valid. Data doesn't exist.

Precondition SmartyKey does exist.
No data associated with SmartyKey.
Result Empty results returned.

HTTP GET - SmartyKey Valid - Property Financial Data Exists

Precondition SmartyKey is valid.
Property data exists.
Result All results for specific smarty-key returned.

Data Sets

  • US Property Data (property/principal)
    • Contains all property data attributes including tax assessor and recorder data
    • Recorder data will be last available financial transaction for the property
  • Financial Data (property/financial)
    • Dataset that contains historical financial data attributes pertaining to the property and property owner.

SSL/TLS Information

Use modern security software and cipher suites.

The leader in location data intelligence

Ready to get started?