This is an archived page. The information on this archived page is no longer current.

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 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.