Road Closed

This information is outdated and is no longer maintained. Get the latest!

 

LiveAddress API's REST endpoint

Making requests to the REST endpoint

Last Updated: March 18, 2013

If 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 or POST 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/or auth-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 nameRequiredDefinition
auth-idY
(if using key pair)
Unique "auth-id" value, obtained from the Key Management page under "Security Keys." Do not use this field for a website key (use auth-token instead).
If used, this value must appear in the query string, not the request body.
auth-tokenYUnique "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_idAny unique identifier that you use to reference the input address. The output will be identical to the input.
streetYThe street address, or a single-line (freeform*) address
* Important information about freeform addresses
street2Any extra address information
secondaryIf used, usually contains apartment or suite number. Should also contain the designator (apt, suite, unit...) or # as the default.
cityThe city name
stateThe state name
zipcodeThe ZIP Code
lastlineThe city, state, and ZIP Code combined
addresseeThe recipient's name or FirmName. Can also be the company.
urbanizationOnly used with Puerto Rican addresses
callbackThe name of the function in which to wrap the JSON response. Typically only used for cross-domain JSONP requests with Javascript.
candidatesThe 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 nameValuesDefaultDefinition
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 website 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
PHP
Python
Ruby

HTTP Status Codes

Responses come with one of the following status codes.

CodeDefinition
200Success. See response body for result payload.
400Bad input. Required fields missing from input or are malformed.
401Unauthorized. Authentication failure; invalid credentials.
402Payment required. No active subscription found.
500Internal 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.