LiveAddress API's REST endpoint

How to make requests to LiveAddress API

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://api.smartystreets.com/street-address

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 "Secret Key Pairs." Do not use this field for an HTML 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.
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
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://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://api.smartystreets.com/street-address?auth-id=<id>&auth-token=<token> [ { street: '1 infinite loop', 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://api.smartystreets.com/street-address?auth-id=<id>&auth-token=<token> <?xml version="1.0" encoding="utf-8"?> <request> <address> <street>1 infinite loop</street> <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.

Method: POST
Content-type: application/json
URL: https://api.smartystreets.com/street-address?auth-id=<id>&auth-token=<token> [ { street: '1 infinite loop', 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://api.smartystreets.com/street-address?auth-id=<id>&auth-token=<token> <?xml version="1.0" encoding="UTF-8" ?> <request> <address> <street>1 infinite loop</street> <city>cupertino</city> <state>ca</state> <zipcode>95014</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.
x-standardize-only "true" or "false" "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.
(eg. 42 Infinite Loop Cupertino, CA 95014)

**BONUS** This header will allow you to perform street lookups. If it's a valid street, you'll get a "dpv_footnotes" response of AAM3.
x-accept-keypair "true" or "false" "false" If you are calling our service from a browser, we strongly suggest that you utilize the HTML Keys (auth-token/host) for security reasons. However, if you absolutely must use the secret key pairs (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 key pair and use it wherever they would like without your consent.
x-suppress-logging When present, this header prevents our system from persisting any address information in your request. By default, we may log the address portion of requests (in such a way that it cannot be associated with the accountholder who submitted the request). This is done so that when we revise our address matching logic, we can be sure it does not adversely affect any output results. By anonymously logging real address inputs, we gain the ability to test our algorithm improvements against a large number of records. If you want to be absolutely sure we do not log your requests, use POST requests to this endpoint of LiveAddress API, and specify this header.

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:

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.

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.