US Street Address API
This page describes how to verify one or more addresses using the Smarty US Address Validation API. You may want to try it out with a free testing account.
(Need to validate a single address? Try our less-technical single address verification tool.)
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-street.api.smarty.com/street-address?auth-id=123&auth-token=abcHere 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-street.api.smarty.com |
|
| Path | /street-address |
|
| Query string | ?auth-id=123&auth-token=abc |
Authentication information, input fields, etc. |
For additional information, please read our article about URL components.
HTTP request: Supported methods/verbs
Supported HTTP 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 address)POST(for sending multiple addresses)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. With "secret key" authentication, both HTTP GET and POST methods are allowed.
HTTP GET: Single address
To send one (and only one) address to our API, simply encode the input field names from the table below along
with the corresponding input values as query string parameters in the URL of your request. Here's an example
that uses the street, city, state, and candidates fields
(line breaks added for readability):
curl -v 'https://us-street.api.smarty.com/street-address?
auth-id=YOUR+AUTH-ID+HERE&
auth-token=YOUR+AUTH-TOKEN+HERE&
street=1600+amphitheatre+pkwy&
city=mountain+view&
state=CA&
candidates=10'
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 GET: Single address with rooftop geocoding
curl -v 'https://us-street.api.smarty.com/street-address?
auth-id=YOUR+AUTH-ID+HERE&
auth-token=YOUR+AUTH-TOKEN+HERE&
street=1600+amphitheatre+pkwy&
city=mountain+view&
state=CA&
candidates=10
HTTP GET: Single address with Project US@ formatting standards
If you have a subscription that allows for Project US@ formatting, to return the acceptable Project US@ results include the format parameter as follows (line breaks added for readability):
curl -v 'https://us-street.api.smarty.com/street-address?
auth-id=YOUR+AUTH-ID+HERE&
auth-token=YOUR+AUTH-TOKEN+HERE&
street=1600+amphitheatre+pkwy&
city=mountain+view&
state=CA&
candidates=10&
format=project-usa'HTTP POST: Multiple addresses
A POST request allows a larger volume of data (MAX: 100 addresses or 32 kilobytes per request) to be sent in
the HTTP Request Body. In this
case, the data should be encoded as a JSON array where each
element in the array is a JSON object with field names identical to those in the field listing below. Here's a
sample request with two addresses being sent (line breaks added for readability):
curl -v 'https://us-street.api.smarty.com/street-address?
auth-id=YOUR+AUTH-ID+HERE&
auth-token=YOUR+AUTH-TOKEN+HERE&'
-H "Content-Type: application/json; charset=utf-8"
--data-binary '
[
{
"street":"1 Santa Claus",
"city":"North Pole",
"state":"AK",
"candidates":10
},
{
"addressee":"Apple Inc",
"street":"1 infinite loop",
"city":"cupertino",
"state":"CA",
"zipcode":"95014",
"candidates":10
}
]'* Project US@ formatting can also be applied to multiple addresses by using the format=project-usa parameter.
HTTP request: Input fields
Each address submitted must have non-blank values for one of the following field combinations to be eligible for a positive address match:
street+city+statestreet+zipcodestreet(entire address in the street field — what we call a "freeform" input)
| Name | Type | Max characters | Default value | Description |
|---|---|---|---|---|
input_id |
string | 36 | blank | [Pass-through value] A unique identifier for this address used in your application; this field will be copied into the output. |
street |
string | 50 | blank | The street line of the address, or the entire address ("freeform" input). Freeform input can be up to 100 characters but only the first 50 will be considered for the street portion of the address. Freeform inputs should NOT include any form of country information (like "USA"). |
street2 |
string | 50 | blank | Any extra address information (e.g., Leave it on the front porch.) |
secondary |
string | 32 | blank | Apartment, suite, or office number (e.g., "Apt 52" or simply "52"; not "Apt52".) |
city |
string | 64 | blank | The city name |
state |
string | 32 | blank | The state name or abbreviation |
zipcode |
string | 16 | blank | The ZIP Code |
lastline |
string | 64 | blank | City, state, and ZIP Code combined |
addressee |
string | 64 | blank | [Pass-through value] The name of the person or company as submitted by the client. This field may also include delivery information such as ATTN: Accounts Payable. This value is taken directly from the addressee input field. Very rarely, this field might be filled automatically with commercial information based on the USPS record. |
urbanization |
string | 64 | blank | The neighborhood (only Puerto Rican addresses) |
candidates |
integer | Max value: 10 | 1 | The maximum number of addresses returned when the input is ambiguous. |
match |
string | 8 | strict |
The match output strategy to be employed for this lookup. Valid values are:
(1) The invalid setting is not compatible with freeform address input. For all
addresses submitted freeform, the API will automatically employ a strict match output
strategy.(2) When submitting addresses in components, setting match to invalid will
prevent the API from finding valid matches for ambiguous address input.(3) Regardless of match type, some inputs will return with an empty array "[]" signifying
that no full or partial match could be made on the input. This can be for a variety of reasons,
primarily in cases where there is poor input and we cannot with confidence return a response.
|
format |
string | 12 | default |
The output format to be employed for this lookup, with an appropriate product subscription. Valid values are:
|
county_source |
string | 10 | blank |
The authoritative source to be used for the county information of the address. Valid values are:
|
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 |
Host |
The Host request header field specifies the internet host of the resource being requested. Optionally, it can also specify a non-default port number. | Host: us-street.api.smarty.com |
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. Additionally, a unique situation can trigger a 401 error when embedded keys are used server-side from a cloud environment or VPN. |
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 maximum size for a request body to this API is 32K (32,768 bytes). |
400 |
Bad request (malformed payload): A GET request lacked a street
field, or the request body of a POST request contained malformed JSON. (example:
submitting an integer value in the ZIP Code field when a string is expected)
|
422 |
Unprocessable entity: A POST request lacked a street field. |
429 |
Too many requests: When using public embedded key authentication, we restrict the number of requests coming from a given source over too short of a time. If you use embedded key authentication, you can avoid this error by adding your IP address as an authorized host for the embedded key in question. |
200 |
OK (success!): A JSON array containing zero or more address matches for the input provided
with the request. If none of the submitted addresses validate, the array will be empty
([]). The structure of the response is the same for both GET and
POST requests.
|
JSON response
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.
Example output - Valid address
[
{
"input_index": 0,
"candidate_index": 0,
"delivery_line_1": "1 Santa Claus Ln",
"last_line": "North Pole AK 99705-9901",
"delivery_point_barcode": "997059901010",
"smarty_key": "1144020281",
"components": {
"primary_number": "1",
"street_name": "Santa Claus",
"street_suffix": "Ln",
"city_name": "North Pole",
"state_abbreviation": "AK",
"zipcode": "99705",
"plus4_code": "9901",
"delivery_point": "01",
"delivery_point_check_digit": "0"
},
"metadata": {
"record_type": "S",
"zip_type": "Standard",
"county_fips": "02090",
"county_name": "Fairbanks North Star",
"carrier_route": "C004",
"congressional_district": "AL",
"rdi": "Commercial",
"elot_sequence": "0001",
"elot_sort": "A",
"latitude": 64.75233,
"longitude": -147.35297,
"coordinate_license": 1,
"precision": "Rooftop",
"time_zone": "Alaska",
"utc_offset": -9,
"dst": true
},
"analysis": {
"dpv_match_code": "Y",
"dpv_footnotes": "AABB",
"dpv_cmra": "N",
"dpv_vacant": "N",
"dpv_no_stat": "Y",
"active": "Y",
"footnotes": "L#"
}
},
{
"input_index": 1,
"candidate_index": 0,
"addressee": "Apple Inc",
"delivery_line_1": "1 Infinite Loop",
// truncated for brevity
}
]Example output - Invalid address
[]HTTP response: Output field definitions
Only non-blank fields will be returned.
Root | Components | Metadata | Analysis | Footnotes
Root
| Field name | Type | Definition |
|---|---|---|
input_id |
varchar(36) | [Pass-through value] Any unique identifier that you use to reference the input address; the output will be identical to the input. |
input_index |
int | The order in which this address was submitted with the others (0 if alone) |
candidate_index |
int |
An input address can match multiple valid addresses. This ties the candidates to the input index.
(e.g., "1 Rosedale Street Baltimore Maryland" will return multiple candidates.) |
addressee |
varchar(64) | [Pass-through value] The name of the person or company as submitted by the client. This field may also include delivery information such as ATTN: Accounts Payable. This value is taken directly from the addressee input field. Very rarely, this field might be filled automatically with commercial information based on the USPS record. |
delivery_line_1 |
varchar(64) |
Contains the first delivery line (usually the street address). This can
include any of the following:
|
delivery_line_2 |
varchar(64) | The second delivery line (if needed). It is common for this field to remain empty. |
last_line |
varchar(64) | City, state, and ZIP Code combined |
delivery_point_barcode |
varchar(12) | 12-digit POSTNET™ barcode; consists of 5-digit ZIP Code, 4-digit add-on code, 2-digit delivery point, and 1-digit check digit. |
smarty_key |
varchar(10) | Smarty's unique identifier for an address. This identifier will only be displayed when an address is submitted with the match parameter set to "enhanced," with an appropriate product subscription. |
components |
[Object] | See "Components" table below. |
metadata |
[Object] | See "Metadata" table below. |
analysis |
[Object] | See "Analysis" table below. |
Components
| Field name | Type | Definition |
|---|---|---|
urbanization |
varchar(64) | The neighborhood, or city subdivision; used with Puerto Rican addresses |
primary_number |
varchar(30) | The house, PO Box, or building number |
street_name |
varchar(64) | The name of the street |
street_predirection |
char(16) | Directional information before a street name (N, SW, etc.) |
street_postdirection |
char(16) | Directional information after a street name (N, SW, etc.) |
street_suffix |
char(16) | Abbreviated value describing the street (St, Ave, Blvd, etc.) |
secondary_number |
varchar(32) | Apartment or suite number, if any |
secondary_designator |
varchar(16) | Describes location within a complex/building (Ste, Apt, etc.) |
extra_secondary_number |
varchar(32) |
Descriptive information about the location of a building within a campus
(e.g., E-5 in "5619 Loop 1604, Bldg E-5, Ste. 101 San Antonio TX") |
extra_secondary_designator |
varchar(16) |
Description of the location type within a campus
(e.g., Bldg, Unit, Lot, etc.) |
pmb_designator |
varchar(16) | The private mailbox unit designator, assigned by a CMRA |
pmb_number |
varchar(16) | The private mailbox number assigned by a CMRA; this value is not verified by Smarty. |
city_name |
varchar(64) | The USPS-preferred city name for this particular address, or an acceptable alternate if provided by the user |
default_city_name |
varchar(64) | The USPS default city name for this 5-digit ZIP Code |
state_abbreviation |
char(2) | The two-letter state abbreviation |
zipcode |
char(5) | The 5-digit ZIP Code |
plus4_code |
varchar(4) | The 4-digit add-on code (more specific than 5-digit ZIP) |
delivery_point |
char(2) | The last two digits of the house/box number, unless an "H" record is matched, in which case this is the secondary unit number representing the delivery point information to form the delivery point barcode (DPBC). |
delivery_point_check_digit |
char(1) | Correction character, or check digit, for the 11-digit barcode |
Metadata
| Field name | Type | Definition |
|---|---|---|
record_type |
char(1) |
Indicates the type of record that was matched. Only given if a DPV match is made.
F — Firm; the finest level of match available for an address. (e.g., Julie Julia 11300 Center Ave Gilroy CA 95020-9257) G — General Delivery; for mail to be held at local post offices. (e.g., General Delivery Provo UT 84601) H — High-rise; address contains apartment or building sub-units. (e.g., 1600 Pennsylvania Ave SE Washington DC 20003-3228) P — Post Office box (e.g., PO Box 4735 Tulsa OK 74159-0735) R — Rural Route or Highway Contract; may have box number ranges. (e.g., RR 2 Box 4560 Anasco PR 00610-9393) S — Street; address contains a valid primary number range. (e.g., 16990 Monterey Rd Lake Elsinore CA 92530-7529) [blank] — No record type because address did not make a valid DPV match |
zip_type |
varchar(32) |
Indicates the type of the ZIP Code for the address that was matched. Only given if a 5-digit match
is made.
Unique — The ZIP Code consists of a single delivery point, pertaining to a US Postal Service customer (like a large business or government agency) that routes all of its own mail internally. Military — The ZIP Code pertains to military units and diplomatic organizations, often in foreign locations. POBox — The ZIP Code is a PO Box ZIP Code and is assigned to a collection of Post Office Boxes. Standard — The ZIP Code does not pertain to any of the above categories. |
county_fips |
char(5) | The 5-digit county FIPS (Federal Information Processing Standards) code. It is a combination of a 2-digit state FIPS code and a 3-digit county code assigned by the NIST (National Institute of Standards and Technology). |
county_name |
varchar(64) | The name of the county in which the address is located |
ews_match |
char(5) |
Early warning system flag; a positive result indicates the street of the address is not yet ready
for mail delivery and that the address will soon be added to the master ZIP+4 file in the coming
weeks or months. This commonly occurs for new streets or streets undergoing a name change.
true — The address was flagged by EWS, preventing a ZIP+4 match. [blank] — Address was not flagged by EWS. |
carrier_route |
char(4) |
The postal carrier route for the address. Consists of a one-letter prefix followed by a three-digit
route designator.
(e.g., C007, R123) C — Carrier Route (commonly termed "City Route") R — Rural Route H — Highway Contract Route B — Post Office Box Section G — General Delivery Unit Routes C770 through C779 pertain to PO Box Street Addresses. |
congressional_district |
char(2) | The congressional district to which the address belongs. Output will be two digits from 01 - 53 or "AL." "AL" means that the entire state (or territory) is covered by a single congressional district. These include Alaska, Delaware, Montana, North Dakota, South Dakota, Vermont, Wyoming, Washington DC, Virgin Islands, and other territories. |
building_default_indicator |
char(1) | Indicates whether the address is the "default" address for a building; for
example, the main lobby
Y — Yes N — No |
rdi |
varchar(12) |
Residential delivery indicator (residential or commercial)
Residential — The address is a residential address. Commercial — The address is a commercial address. [blank] — This happens when the address is invalid or we don't have enough information to ascertain RDI status. The Bulk Address Validation Tool translates a [blank] RDI value to "Unknown." Note: For some reason, known only to the US Postal Service, PO Boxes are always marked as "Residential." |
elot_sequence |
varchar(4) | eLOT (Enhanced Line of Travel) 4-digit sequence number |
elot_sort |
varchar(4) |
eLOT (Enhanced Line of Travel) product was developed to give mailers the ability to sort their
mailings by line of travel sequence.
A — Ascending D — Descending [blank] — Address not submitted for eLOT |
latitude |
decimal(9,6) | The horizontal component used for geographic positioning, ***based on the WGS84 coordinate system***. It is the angle between 0° (the equator) and ±90° (north or south) at the poles. It is the first value in an ordered pair of (latitude, longitude). A negative number denotes a location below the equator; a positive number is above the equator. Combining lat/long values enables you to pinpoint addresses on a map. |
longitude |
decimal(9,6) | The vertical component used for geographic positioning. It is the angle between 0° (the Prime Meridian) and ±180° (westward or eastward). It is the second number in an ordered pair of (latitude, longitude). A negative number indicates a location west of Greenwich, England; a positive number east. Combining lat/long values enables you to pinpoint addresses on a map. |
coordinate_license |
int | The license ID for the geographic coordinate returned. See the licensing table below for more details. |
precision |
varchar(18) |
Indicates the precision of the latitude and longitude values.
Unknown — Coordinates not known. Reasons could include: address is invalid, military address (APO or FPO), lat/lon coordinates not available. Zip5 — Accurate to a 5-digit ZIP Code level (least precise) Zip6 — Accurate to a 6-digit ZIP Code level Zip7 — Accurate to a 7-digit ZIP Code level Zip8 — Accurate to an 8-digit ZIP Code level Zip9 — Accurate to a 9-digit ZIP Code level (most precise with the basic subscription) Street — Accurate to a position along the street proportional to the house/building number. Parcel — Accurate to the centroid of a property parcel. Requires the US Rooftop Geocoding subscription. Rooftop — Accurate to the rooftop of a structure for this address. Requires the US Rooftop Geocoding subscription. Note: Concerning addresses for which the ZIP9 precision is not available, the ZIP# precision is interpolated based on neighboring addresses. Thus, ZIP7 is an average of all the lat/long coordinates of nearby ZIP Codes that share those first 7 digits. |
time_zone |
varchar(48) |
Indicates the common name of the time zone associated with the address.
Valid Responses Alaska, Atlantic, Central, Eastern, Hawaii, Mountain, None, Pacific, Samoa, UTC+9, UTC+10, UTC+11, UTC+12 |
utc_offset |
decimal(4,2) |
Indicates the number of hours the time zone is offset from Universal Time Coordinated (UTC), the
international time standard, also known as Greenwich Meridian Time (GMT).
Valid responses -11, -10, -9, -8, -7, -6, -5, -4, 0, 9, 10, 11, 12 |
dst |
char(5) |
Indicates if the time zone "obeys," or, in other words, adjusts their clocks forward and back with
the seasons. This information is particularly useful to determine time in other time zones with
areas that may or may not use daylight saving time - for example, Arizona, Hawaii, and, of all
places, Indiana.
true — Time zone observes daylight saving time. If dst is absent from the response, then time zone does not observe daylight saving time. |
Analysis
| Field name | Type | Definition |
|---|---|---|
dpv_match_code |
varchar(1) |
Status of the Delivery Point Validation (DPV). This indicates whether or not the address is present
in the USPS data.
Y — Confirmed; entire address is present in the USPS data. (To be certain the address is actually deliverable, verify that the dpv_vacant field has a value of
N. You may also want to verify that the dpv_no_stat field has a value of
N. However, the USPS is often several months behind in updating this data point, so
only rely on the dpv_no_stat data if you are fully aware of its weaknesses and
limitations.)
(e.g., 1600 Amphitheatre Pkwy Mountain View, CA) N — Not confirmed; address is not present in the USPS data. S — Confirmed by ignoring secondary info; the main address is present in the USPS data, but the submitted secondary information (apartment, suite, etc.) was not recognized. (e.g., 62 Ea Darden Dr Apt 298 Anniston, AL) D — Confirmed but missing secondary info; the main address is present in the USPS data, but it is missing secondary information (apartment, suite, etc.). (e.g., 122 Mast Rd Lee, NH) [blank or null] — The address is not present in the USPS database. |
dpv_footnotes |
varchar(32) |
Information related to the delivery point validation of this address. All these footnotes have a
length of 2 characters, and
there may be up to 14 footnotes.
AA — Street name, city, state, and ZIP are all valid. (e.g., 2335 S State St Ste 300 Provo UT) A1 — Address not present in USPS data. (e.g., 3214 N University Ave New York NY) BB — Entire address is valid. (e.g., 2335 S State St Ste 300 Provo UT) CC — The submitted secondary information (apartment, suite, etc.) was not recognized. Secondary number is NOT REQUIRED for delivery. (e.g., 3331 Erie Ave Apt 2 Cincinnati OH 45208) C1 — The submitted secondary information (apartment, suite, etc.) was not recognized. Secondary number IS REQUIRED for delivery. (e.g., 2335 S State St Ste 500 Provo UT) F1 — Military or diplomatic address (e.g., Unit 2050 Box 4190 APO AP 96278) G1 — General delivery address (e.g., General Delivery Provo UT 84601) M1 — Primary number (e.g., house number) is missing. (e.g., N University Ave Provo UT) M3 — Primary number (e.g., house number) is invalid. (e.g., 16 N University Ave Provo UT) N1 — Address is missing secondary information (apartment, suite, etc.) which IS REQUIRED for delivery.. (e.g., 2335 S State St Provo UT) PB — PO Box street style address. (e.g., 555 S B B King Blvd Unit 1 Memphis TN 38103) P1 — PO, RR, or HC box number is missing. (e.g., Dept 126 Denver CO 802910126) P3 — PO, RR, or HC box number is invalid. (e.g., PO BOX 60780 FAIRBANKS AK 99706) RR — Confirmed address with private mailbox (PMB) info. (e.g., 3214 N University Ave #409 Provo UT) R1 — Confirmed address without private mailbox (PMB) info. (e.g., 3214 N University Ave Provo UT) R7 — Confirmed as a valid address that doesn't currently receive US Postal Service street delivery. (e.g., 6D Cruz Bay St John VI 00830) TA — Primary number was matched by dropping trailing alpha. (e.g., 4-C PENINSULA CTR RANCHO PALOS VERDES CA 90274) U1 — Address has a "unique" ZIP Code. (e.g., 100 North Happy Street 12345) Here are some common combinations:
|
dpv_cmra |
varchar(1) |
Indicates whether the address is associated with a Commercial Mail
Receiving Agency (CMRA), also known as a private mailbox (PMB) operator.
A CMRA is a business through which USPS mail may be sent or received,
for example the UPS Store and Mailboxes Etc.
Y — Address is associated with a valid CMRA. N — Address is not associated with a valid CMRA. [blank] — Address was not submitted for CMRA verification. |
dpv_vacant |
varchar(1) |
Indicates that a delivery point was active in the past but is currently vacant (in most cases,
unoccupied over 90 days) and is not receiving deliveries. This status is often obtained when mail
receptacles aren't being emptied and are filling up, so mail is held at the post office for a
certain number of days before the delivery point is marked vacant.
Y — Address is vacant. N — Address is not vacant. [blank] — Address was not submitted for vacancy verification. |
dpv_no_stat |
varchar(1) |
Indicates that a delivery point is listed as "no-stat" by the USPS. Technically, that means the USPS
is temporarily declaring the address undeliverable. In practice, however, the USPS is often several
months behind in removing addresses from the "no-stat" list, so only rely on this data point if you
are fully aware of its weaknesses and limitations.
Y — USPS lists the address as "no-stat." N — USPS does not list the address as "no-stat." [blank] — Address was not submitted for "no-stat" verification. |
active |
varchar(1) |
The API still returns this field, but in practical terms, it is deprecated. This field will contain
a value of Y for every address submitted.
|
footnotes |
varchar(24) |
Indicates which changes were made to the input address. Footnotes are delimited by a #
character. See the footnotes table below for details.
|
lacslink_code |
varchar(2) |
The reason for the LACSLink indication that was given (below)
A — Match: Address provided. LACSLink record match was found, and a converted address was provided. 00 — No Match. No converted address. No soup for you! 09 — Match: No new address. LACSLink matched an input address to an old address which is a "high-rise default" address; no new address was provided. 14 — Match: No conversion. Found a LACSLink record, but couldn't convert the data to a deliverable address. 92 — Match: Dropped secondary number. LACSLink record was matched after dropping the secondary number from input. [blank] — No LACSLink lookup attempted. |
lacslink_indicator |
varchar(1) |
Indicates whether there is an address match in the LACSLink database.
Y — LACS record match; a new address could be furnished because the input record matched a record in the master file. S — LACS record - secondary number dropped; the record is a ZIP+4 street level or high-rise match. The input record matched a master file record, but the input address had a secondary number and the master file record did not. N — No match; a new address could not be furnished; the input record could not be matched to a record in the master file. F — False positive; a false positive record was detected. [blank] — No LACSLink lookup attempted. |
suitelink_match |
varchar(5) |
Indicates a match (or not) to the USPS SuiteLink data.
SuiteLink
attempts to provide secondary information such as "suite" or "apartment" whenever there is a match
based on address and company name.
true — There was a SuiteLink match and the result is provided. (e.g.,D. L. Evans Bank, 545 E University Pkwy Orem UT 84097) false — There was no SuiteLink match. |
enhanced_match |
varchar(64) |
When an address is submitted with the match parameter set to "enhanced," this field will contain additional information about the result. Multiple values may be present, separated by commas. Additional values will be added from time to time. The current possible values are: none — No address match was found. non-postal-match — A match was found within additional, non-postal address data. postal-match — A match was found within postal address data. missing-secondary — The address should have a secondary (e.g., apartment), but none was found in the input. unknown-secondary — The provided secondary information did not match a known secondary within the address data. ignored-input — The provided input contained information that was not used for a match. |
Footnotes
This table describes possible values in the footnotes field from the analysis object.
(Example addresses may be changed at any time due to the nature of the data.)
| Value | Definition | Details |
|---|---|---|
| A# | Corrected ZIP Code |
The address was found to have a different 5-digit ZIP Code than the one submitted. The correct ZIP
Code is shown in the zipcode field.
(e.g., 4800 Fairmount Ave Kansas City MO 64111) |
| B# | Corrected city/state spelling |
The spelling of the city name and/or state abbreviation in the submitted address was found to be
different than the standard spelling. The standard spellings are shown in the city_name
and state_abbreviation fields.
(e.g., 370 Main St, Frenchville, ME 04756) |
| C# | Invalid city/state/ZIP |
The ZIP Code in the submitted address could not be found because neither a valid city and state, nor
valid 5-digit ZIP Code was present. Smarty recommends that the customer check the accuracy of
the submitted address.
(e.g., 200 Camp Drive 25816) |
| D# | No ZIP+4 assigned |
This address is not present in the USPS data. Smarty recommends that the customer check the
accuracy of the submitted address.
(e.g., 2288 S Bethel Ave Sanger, CA 93657) |
| E# | Same ZIP for multiple | Multiple records were returned, with the same 5-digit ZIP Code. |
| F# | Address not found |
The address, exactly as submitted, could not be found in the city, state, or ZIP Code provided. Some possible reasons for this are: the primary number is missing, the street is missing, or the street is too badly misspelled to understand
(e.g., 2600 Rafe Lane Jackson MS 39201) |
| G# | Used addressee data |
Information in the addressee input field was determined to be part of the address. It
was moved out of the addressee field and incorporated into the street
field.
(e.g., 97 Taylor St apt 3F Taylor Manchester NH) |
| H# | Missing secondary number |
The address as submitted is missing a secondary number (apartment, suite, etc.). Smarty
recommends that the customer check the accuracy of the submitted address and add the missing
secondary number to ensure the correct Delivery Point Barcode (DPBC).
(e.g., 109 Wimbledon Sq Chesapeake VA 23320) |
| I# | Insufficient/ incorrect address data | More than one ZIP+4 Code was found to satisfy the address as submitted. The submitted address did not contain sufficiently complete or correct data to determine a single ZIP+4 Code. Smarty recommends that the customer check the accuracy and completeness of the submitted address. For example, a street may have a similar address at both the north and south ends of the street. |
| J# | Dual address |
The input contained two addresses. For example: 123 MAIN ST PO BOX 99.
(e.g., PO Box 38606 30th Street Train Station Philadelphia PA 19104) |
| K# | Cardinal rule match |
Although the address as submitted is not valid, we were able to find a match by changing the
cardinal direction (North, South, East, West). The cardinal direction we used to find a match is
found in the components.
(e.g., 315 W Cesar Chavez St Austin TX) |
| L# | Changed address component |
An address component (i.e., directional or suffix only) was added, changed, or deleted in order to
achieve a match.
(e.g., 213 S QUANAH RUSSELLVILLE AR 72801) |
| LL# or LI# |
Flagged address for LACSLink | The input address matched a record that was LACS-indicated, that was submitted to LACSLink for processing. This does not mean that the address was converted; it only means that the address was submitted to LACSLink because the input address had the LACS indicator set. |
| M# | Corrected street spelling | The spelling of the street name was changed in order to achieve a match. |
| N# | Fixed abbreviations | The delivery address was standardized. For example, if STREET was in the delivery address, Smarty will return ST as its standard spelling. |
| O# | Multiple ZIP+4; lowest used |
More than one ZIP+4 Code was found to satisfy the address as submitted. The lowest ZIP+4 add-on may
be used to break the tie between the records.
(e.g., 313 E 3 St Nescopeck PA 18635) |
| P# | Better address exists | The delivery address is matchable, but it is known by another (preferred) name. For example, in New York, NY, AVENUE OF THE AMERICAS is also known as 6TH AVE. An inquiry using a delivery address of 39 6th Avenue would be flagged with Footnote P#. If the given address is acceptable (meaning it is the same as the preferred version), then it will not be changed and the footnote will be returned (e.g., 7202 Panam Expy S San Antonio TX 78224). If the input address is unacceptable (meaning it is recognized but not the preferred version), then it will be changed to the preferred version and the footnote is returned (e.g., 131 Stone Farm Lebanon NH 03766) |
| Q# | Unique ZIP match |
The address has a "unique" ZIP Code
(e.g., 645 Swick Hill Street Charlotte NC 28263) |
| R# | No match; EWS: Match soon | The delivery address is not yet matchable, but the US Postal Service Early Warning System file indicates that a match will be available soon. |
| S# | Unrecognized secondary address |
The secondary information (apartment, suite, etc.) was not recognized as part of the USPS data.
(e.g., 1409 Hueytown Rd Apt 1781 Bessemer AL 35023) |
| T# | Multiple response due to magnet street syndrome |
The search resulted in a single response; however, the record matched was flagged as having magnet
street syndrome, and the input street name components (pre-directional, primary street name,
post-directional, and suffix) did not exactly match those of the record. A "magnet street" is one
having a primary street name that is also a suffix or directional word, having either a
post-directional or a suffix (i.e., 2220 PARK MEMPHIS TN logically matches to a ZIP+4 record
2200-2258 PARK AVE MEMPHIS TN 38114-6610), but the input address lacks the suffix "AVE" which is
present on the ZIP+4 record. The primary street name "PARK" is a suffix word. The record has either
a suffix or a post-directional present. Therefore, in accordance with CASS requirements, a ZIP+4
Code must not be returned. The multiple response return code is given since a "no match" would
prevent the best candidate.
(e.g., 84 Green St Northampton MA) |
| U# | Unofficial city name |
The city name in the submitted address is an alternate city name that is not accepted by the US Postal Service. The preferred city name is output in the city_name field.
(e.g., 150 Ken Visage Ln LaFayette GA) |
| V# | Unverifiable city/state |
The city and state in the submitted address could not be verified as corresponding to the given
5-digit ZIP Code. This comment does not necessarily denote an error; however, Smarty
recommends that the customer check the accuracy of the city and state in the submitted address.
(e.g., 7210 17 Avenue New York NY 11204 |
| W# | Invalid delivery address | The USPS does not provide street delivery service for this ZIP Code. The USPS requires the use of a PO Box, General Delivery, or Postmaster for delivery within this ZIP Code. |
| X# | Default Unique ZIP Code |
The address has a "unique" ZIP Code with a default ZIP+4 code
(e.g., 2020 S LAND OLAKES BLVD APT 9 FORT WORTH TX 76199 |
| Y# | Military match |
The address has a military or diplomatic ZIP Code.
(e.g., PSC 10 Box 1324 APO AE 09142) |
| Z# | Matched with ZIPMOVE |
The ZIPMOVE product shows which ZIP+4 records have moved from one ZIP Code to another. If an input address matches a ZIP+4 record which the ZIPMOVE product indicates has moved, the search is performed again in the new ZIP Code.
(e.g., 26131 State Highway 37 Seligman MO 65745) |
Geographic coordinate data licenses
| ID | Name | Description |
| 0 | Smarty | Results with this coordinate license are provided with an open/unrestricted license. Attribution is optional. |
| 1 | Smarty proprietary | Smarty hereby grants a limited, worldwide, non-exclusive, non-transferable (except as authorized herein), revocable license to use this geocoding coordinate consisting of latitude and longitude values and associated metadata for internal business use purposes only and for the duration of the term stated for the online subscription. |
How to interpret the raw data output
This part of the document explains how to determine the validity and deliverability of a US address based on the raw output from Smarty's US Street Address API.
These suggestions are designed for customers using one or more of our address verification plans with a "Core" or "Rooftop" license.
Customers who are using one of our older "Legacy" licenses can ask for a different version of these suggestions that is applicable to them.
Feel free to jump to the section most applicable to you and your products:
US Street Address API Tool's default responses
The logic proposed below is based on the output from the following specific output fields as discussed in our US Address Verification documentation:
- enhanced_match
- dpv_footnotes
- record_type
- dpv_vacant
- dpv_no_stat
The most important of these is "enhanced_match". This is not a default field; you'll need to ensure it's marked. The "enhanced_match" field will only be included in the output if the "match" input parameter is explicitly set to "enhanced".
It's important to note that when we say an address is valid, we're referring to the output version of the address, as shown in the output fields "delivery_line_1" and "last_line", not what the user typed in initially. This is because, in some cases, this will have been changed to achieve a match.
In the descriptions below, "secondary" means "subunit," like an apartment or suite number.
Here is an example of typical raw responses and how they should be interpreted:
IF
"enhanced_match" contains [none]
INTERPRETATION
The address isn't a real US address, meaning it isn't in the USPS database nor Smarty's proprietary non-USPS/non-postal data. (We have more than 20 million non-USPS addresses in our dataset.)
IF
"enhanced_match" includes [postal-match] and does NOT include [missing-secondary] or [unknown-secondary]
INTERPRETATION
The address is a real address, present in the USPS data, and there’s no concern about any secondary information such as a unit number. The address is completely valid, as shown in the output.
IF
"enhanced_match" includes [postal-match] and [missing-secondary] AND "dpv_footnotes" include [N1]
INTERPRETATION
The address is a real address, present in the USPS data, but the USPS requires secondary information for this address, and none was submitted. In a user-facing context, you may want to prompt the user to add an apartment or suite number in a pop-up window or notification bar.
IF
"enhanced_match" includes [postal-match] and [missing-secondary] AND "dpv_footnotes” do NOT include [N1]
INTERPRETATION
The address is a real address, present in the USPS data, and the address has secondary indicators associated with it. However, without the "N1" dpv_footnote, secondary information is NOT required for delivery. This means that the main address itself, without any apartment or suite information, is a valid USPS delivery point.
IF
"enhanced_match" includes [postal-match] and [unknown-secondary] AND "dpv_footnotes" include [C1]
INTERPRETATION
The address is a real address, present in the USPS data, but the USPS requires secondary information for this address, and the secondary information submitted wasn’t recognized. (In a user-facing context, you may want to prompt the user to correct their apartment or suite number.)
IF
"enhanced_match" includes [postal-match] and [unknown-secondary] AND "dpv_footnotes" include [CC]
INTERPRETATION
The address is a real addressthat is present in the USPS data. The secondary information submitted wasn’t recognized, but it isn’t needed for regular delivery to this address.
IF
"enhanced_match" includes [non-postal-match] and does NOT include [missing-secondary] or [unknown-secondary]
INTERPRETATION
The address is a real address, but it isn’t present in the USPS data. There’s no concern about any secondary information. The address is completely valid, as shown in the output. A “non-postal-match” is what we refer to as a non-USPS address - a valid address that isn’t in the USPS database. Smarty provides you with more than 20 million you can match against. Even though the address is valid, USPS won’t deliver to these non-postals (although other carriers might).
IF
"enhanced_match" includes [non-postal-match] and [missing-secondary]
INTERPRETATION
The address is a real address, but it isn’t present in the USPS data. The address has secondaries associated with it, and secondary information might be needed for delivery. (In a user-facing context, you may want to prompt the user to add an apartment or suite number.)
IF
"enhanced_match" includes [non-postal-match] and [unknown-secondary]
INTERPRETATION
The address is a real address, but it isn’t present in the USPS data, and the submitted secondary information wasn’t recognized. (In a user-facing context, you may want to prompt the user to correct the apartment or suite number.)
Special case logic regarding deliverability
The following is additional logic that would be needed to determine if a particular address is deliverable by certain mail carriers like non-USPS such as FedEx, UPS, DHL etc.
To verify an address is deliverable by FedEx, UPS, or other carriers that are NOT the USPS:
Make sure "record_type" does NOT equal [P], which would indicate a PO Box address.
To verify an address is deliverable by the USPS:
Make sure "dpv_vacant" = [N], "dpv_no_stat" = [N], and the "dpv_footnotes" field does NOT contain [R7].
XML usage
While we prefer JSON for its flexibility and ease of use, our API will still accept and return XML data. To send
XML in a POST request, set the Content-Type request header to
application/xml; charset=utf-8. To receive XML in the response, set the Accept request
header to application/xml; charset=utf-8. Here's a simple example:
curl -v -X POST 'https://us-street.api.smarty.com/street-address?
auth-id=YOUR+AUTH-ID+HERE&
auth-token=YOUR+AUTH-TOKEN+HERE'
-H 'Content-Type: application/xml; charset=utf-8'
-H 'Accept: application/xml; charset=utf-8'
--data-binary '
<request>
<address>
<addressee>Apple Inc</addressee>
<street>1 infinite loop</street>
<street2>po box 42</street2>
<city>cupertino</city>
<state>CA</state>
<zipcode>84014</zipcode>
<candidates>10</candidates>
</address>
<address>
<street>1600 Pennsylvania ave</street>
<zipcode>20500</zipcode>
<candidates>10</candidates>
</address>
<address>
<street>123 main st. 12345</street>
</address>
</request>'JSONP usage
JSONP has been deprecated and is no longer supported.