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 are some example URLs:
https://us-enrichment.api.smarty.com/lookup/1000000/property/principal?auth-id=12345&auth-token=abcdef
https://us-enrichment.api.smarty.com/lookup/1000000/geo-reference?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/principal /property/financial /geo-reference |
Specify one of the available Datasets |
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
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 |
ETag |
The ETag header provides the ability to check if a record has been updated since the last query.
Every query to the API will return an ETag header which represents a hash of the record in the response. This value may be stored and used in subsequent queries for that same record. If the record data has NOT been updated since the last query, it will return a 304 (Not Modified) and the client will not be charged for the query. (The 304 response does not contain a body.) If the record data HAS been updated, the latest version of the record will be returned along with a new ETag value. Important: Only the latest ETag value is valid for each record. This feature is NOT designed to retrieve past record versions. Also note that the ETag value will change if ANY data in the record has been updated, regardless of which attributes are requested using the include and exclude parameters.
|
ETag: AUHQQBIPBQDAYAA |
Input Fields
Name | Type | Default Value | Description |
---|---|---|---|
include |
string | (empty) |
List of attributes that are allowed to be included in the response.
This list can include Group names and Attribute names
separated by commas. All values must be lowercase.
If the record in the response does not have a value for that attribute, it will not be included in the response. |
exclude |
string | (empty) | List of attributes that are not allowed to be included in the response. This list can include Group names and Attribute names separated by commas. All values must be lowercase. |
All input field parameters must be UTF-8 and then URL encoded.
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 |
---|---|
200 |
OK (success!): The response body is a JSON object containing metadata about the results and zero or one addresses from the input provided with the request. See the annotated example below for details. An ETag header value will also be returned which represents a hash of the current record. (See ETag header in the request.) |
304 |
Not Modified: The requested ETag header represents the latest data available. |
400 |
Bad Request (Malformed Payload): The request body was blank or otherwise malformed. |
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. |
413 |
Request Entity Too Large: The request body was larger than 64 Kilobytes. |
422 |
Unprocessable Content: Some parameter values are not correct. Detailed messages will describe the problem. |
429 |
Too Many Requests: We restrict the number of requests coming from a given source over too short of a time. |
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",
...
}
],
...
}
}
]
Example Response - geo-reference
Dataset
[
{
"smarty_key": "1601354568",
"data_set_name": "geo-reference",
"attributes": {
"census_block": {
"accuracy": "block",
"geoid": "530050109014000"
},
"census_county_division": {
"accuracy": "exact",
"code": "5300592768",
"name": "Richland-Kennewick"
},
"census_tract": {
"code": "0109.01"
},
"core_based_stat_area": {
"code": "28420",
"name": "Kennewick-Richland, WA"
},
"place": {
"accuracy": "exact",
"code": "5335275",
"name": "Kennewick",
"type": "incorporated"
}
}
}
]
Data Sets
- US Property Principal 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
- US Property Financial Data (
property/financial
)- Dataset that contains historical financial data attributes pertaining to the property and property owner.
- US GeoReference Data (
geo-reference
)- The GeoReference Data product provides the ability to append useful geographic data, like census block id, to geocoded addresses.
Attribute Groups (For US Property Datasets)
The following attribute groups are supported in the
include
and exclude
input parameters when performing a request for
Group Name | Description | Attributes Included |
---|---|---|
group_financial |
Financial attributes in the Principal Dataset records |
assessed_improvement_percent
|
group_location |
Location attributes in the Principal Dataset records |
block1
|
group_structural |
Structural attributes in the Principal Dataset records |
1st_floor_sqft
|
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 SmartyKey returned. |
HTTP GET - SmartyKey Has No Property Data
Precondition | SmartyKey has no property data |
Action | https://us-enrichment.api.smarty.com/lookup/111111/property/principal |
Result | Empty results returned. |
HTTP GET - Use include
and exclude
Parameters Containing a Group in Principal Data
Precondition | SmartyKey is valid. Property data exists. |
Action | https://us-enrichment.api.smarty.com/lookup/111111/property/principal?include=group_structural&exclude=attic_flag,boat_lift |
Result |
Available data for that SmartyKey within the attribute group
group_structural , excluding
the attic_flag and boat_lift attributes.
|
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 SmartyKey returned. |
HTTP GET - Use of ETag Header Where Data Has Not Been Updated
Precondition | SmartyKey is valid. Property data exists. An ETag value from a previous query and the data has not changed. |
Action | Header: ETag: AABBCCDD https://us-enrichment.api.smarty.com/lookup/111111/property/financial |
Result | HTTP 304 indicating that the data has not changed. There was no charge for the lookup. |
HTTP GET - Use of ETag Header Where Data Has Changed
Precondition | SmartyKey is valid. Property data exists. An ETag value from a previous query and the data has changed. |
Action | Header: ETag: AABBCCDD https://us-enrichment.api.smarty.com/lookup/111111/property/financial |
Result | All results for specific SmartyKey returned. A new ETag value is also returned. |