LiveAddress API's REST endpoint
Making requests to the REST endpoint
Last Updated: March 18, 2013If you can already make requests, see how to parse the JSON/XML response.
LiveAddress API is configured to receive HTTP requests at the following URL:
https://us-street.api.smartystreets.com/street-address
- Use
GET
orPOST
verbs. - All query string parameters must be properly URL-encoded.
- You must, must, must account for dynamic IP addressing. STATIC IP ADDRESSES WILL BREAK YOUR CODE.
- Ensure the
auth-id
and/orauth-token
values are in the query string. - Spaces in a query string parameter may be encoded as
+
for readability. - For
POST
requests, the request body must be a JSON or XML string (see below) identified by the content type of the request.
Request/input parameters
You may include the following fields as input to the API:
Parameter name | Required | Definition |
---|---|---|
auth-id |
Y
(if using key pair) |
Unique "auth-id" value, obtained from the Key
Management
page under "Security Keys."
Do not use this field for an embedded key (use auth-token instead).
If used, this value must appear in the query string, not the request body. |
auth-token |
Y |
Unique "auth-token" value, obtained from the Key Management page.
If using a secret key pair, this must be associated with an ID in the auth-id field.This value must appear in the query string, not the request body. |
input_id |
Any unique identifier that you use to reference the input address. The output will be identical to the input. | |
street |
Y |
The street address, or a single-line (freeform*) address
* Important information about freeform addresses |
street2 |
Any extra address information | |
secondary |
If used, usually contains apartment or suite number. Should also contain the designator (apt, suite, unit...) or # as the default. | |
city |
The city name | |
state |
The state name | |
zipcode |
The ZIP Code | |
lastline |
The city, state, and ZIP Code combined | |
addressee |
The recipient's name or FirmName. Can also be the company. | |
urbanization |
Only used with Puerto Rican addresses | |
callback |
The name of the function in which to wrap the JSON response. Typically only used for cross-domain JSONP requests with Javascript. | |
candidates |
The maximum number of valid addresses returned when the input address is ambiguous. (Max = 10, default = 1) Will this give me address suggestions? |
Examples: a single address
Method: GET
https://us-street.api.smartystreets.com/street-address?street=1600+Amphitheatre+Parkway&city=Mountain+View&state=CA&zipcode=94043&candidates=5&auth-id=<your
id here>&auth-token=<your token here>
Method: POST
Content-type: application/json
URL:
https://us-street.api.smartystreets.com/street-address?auth-id=<id>&auth-token=<token>
[
{
"addressee": "Apple Inc",
"street": "1 infinite loop",
"street2": "po box 42",
"city": "cupertino",
"state": "ca",
"zipcode": "95014",
"candidates": 10
}
]
Notice how the request body is an array of address objects. The LiveAddress API is
designed to receive an array of addresses because it can handle up to 100 addresses
per request. Even if you submit only one address, it must be inside an array.
Method: POST
Content-type: text/xml
URL:
https://us-street.api.smartystreets.com/street-address?auth-id=<id>&auth-token=<token>
<?xml version="1.0" encoding="utf-8"?>
<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>
</request>
Examples: multiple addresses
Multi-address requests can only be sent via POST. You can submit up to 100 addresses per request. Hint: Don't URL-encode the address here.
Method: POST
Content-type: application/json
URL:
https://us-street.api.smartystreets.com/street-address?auth-id=<id>&auth-token=<token>
[
{
"addressee": "Apple Inc",
"street": "1 infinite loop",
"street2": "po box 42"
"city": "cupertino",
"state": "ca",
"zipcode": "95014",
"candidates": 10
},
{
"street": "1600 Pennsylvania ave",
"zipcode": "20500",
"candidates": 10
},
{
"street": "123 main st. 12345"
}
]
Method: POST
Content-type: text/xml
URL:
https://us-street.api.smartystreets.com/street-address?auth-id=<id>&auth-token=<token>
<?xml version="1.0" encoding="UTF-8" ?>
<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>
Note that queries like this will deduct 3 lookups on your account because you submitted 3 valid addresses.
HTTP Request Headers
You may specify the following HTTP headers with requests to the API to modify its behavior:
Parameter name | Values | Default | Definition |
---|---|---|---|
Content-Type |
"application/json" or "application/xml" or "text/xml" |
"application/json" | Here you can specify the format of the input data that you are sending to the API. For HTTP POST requests only. |
Accept |
"application/json" or "application/xml" or "text/xml" |
"application/json" | This allows you to specify the format of response data that the API provides. |
?match=range |
"false" |
When false, results from the API will consist of DPV
confirmed
(deliverable) addresses. When true, results from the API will include DPV confirmed addresses as well as
addresses
that match the USPS ZIP+4 listings. This is a more inclusive option but may require more
inspection of the results
to determine if an address is usable by your application. It means that your response will now include any address whose primary number fits into a valid range for the given street. So if the valid range is 1-99 (odd) and 2-98 (even) and you submit "42," you will get a positive response from the API because the address falls within the appropriate range. Remember, it doesn't mean the address is deliverable. (e.g., 42 Infinite Loop Cupertino, CA 95014) |
|
?match=invalid |
"false" |
When true, results from the API will include candidates that may not be valid and/or deliverable.
All results will be marked with
Footnotes and
DPV Footnotes accordingly.
This option is the most inclusive option for the API. As a side-effect of this,
addresses that would normally return multiple candidates will be returned as a single
candidate with a footnote indicating that there are multiple candidates.
If you don't plan on setting this header to "true", it is best to remove this request header altogether. |
|
x-accept-keypair |
"true" or "false" | "false" | If you are calling our service from a browser, we strongly suggest that you utilize the embedded keys (auth-token/host) for security reasons. However, if you absolutely must use the security keys (auth-id+auth-token), simply add this header to your request and set the value to "false". BE AWARE that this opens you open to a potential security risk whereby someone can easily extract your security keys and use them wherever they would like without your consent. |
JSONP Requests
Because of browser security restrictions, you can't perform a traditional AJAX request to our API using Javascript. A common workaround is to perform what's known as a JSONP request. See how to do that on our Javascript help page.
XML Requests
The schema for XML request and response payloads is documented in the XSD files provided below:
- Request XSD file
- Response XSD file — Note: The structure of our XML response may change as we roll out improvements to the API. Your code should be able to support any additional or missing fields in the XML. We'll update the response XSD file should this happen.
These files can be used in conjunction with various 3rd-party tools/libraries to generate code that corresponds to the XML schema contained in the XSD files that will allow easier mapping between XML and code. Below is a listing of commonly used tools in various programming languages as well as where to go to find more information:
Java
.NET
- Xsd2Code - NOTE: When using this tool to generate classes from our XSD files you must set the GenerateXMLAttributes option to True (see the answer to this question)
- Related discussion
PHP
Python
Ruby
HTTP Status Codes
Responses come with one of the following status codes.
Code | Definition |
---|---|
200 | Success. See response body for result payload. |
400 | Bad input. Required fields missing from input or are malformed. |
401 | Unauthorized. Authentication failure; invalid credentials. |
402 | Payment required. No active subscription found. |
500 | Internal server error. General service failure; retry request. |
Output
The API responds with a JSON or XML payload containing the results.
Sample code
We maintain an active GitHub repository called LiveAddressSamples which has sample code in several languages and platforms. Some Javascript examples are found in our documentation, and working samples you can demo may be found on jsFiddle.