US Address Enrichment API
This page describes how to retrieve data from various different datasets using the Smarty US Address Enrichment API.
Contents
- HTTP Request
- HTTP Response
- Supplementary Materials
HTTP Request: URL Composition
Proper URL construction is required for all API requests. Here is an example URL:
https://us-enrichment.api.smarty.com/lookup/1000000/property/principal?auth-id=12345&auth-token=abcdef
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-enrichment.api.smarty.com |
|
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
/financial
|
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. |
Action | https://us-enrichment.api.smarty.com/lookup/111111/property/principal |
Result | All results for specific smarty-key returned. |
HTTP GET - SmartyKey Not Valid
Precondition | SmartyKey does not exist. |
Action | https://us-enrichment.api.smarty.com/lookup/111111/property/principal |
Result | Empty results returned. |
HTTP GET - SmartKey Valid. Data doesn't exist.
Precondition | SmartyKey does exist. No data associated with SmartyKey. |
Action | https://us-enrichment.api.smarty.com/lookup/111111/property/principal/ |
Result | Empty results returned. |
HTTP GET - SmartyKey Valid - Property Financial Data Exists
Precondition | SmartyKey is valid. Property data exists. |
Action | https://us-enrichment.api.smarty.com/lookup/111111/property/financial/ |
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.