US Extract API - Address Extraction Made Easy

This page describes how to use the extraction endpoint to find and validate addresses in arbitrary text input.


  1. HTTP Request
    1. URL Composition
    2. Request Methods
    3. Input Fields
    4. Headers
  2. HTTP Response
    1. Status Codes and Results
    2. Annotated Response
  3. Supplementary Materials
    1. Subscription Usage
    2. SSL/TLS Information
    3. Try the demo

HTTP Request: URL Composition

Proper URL construction is required for all API requests. Here is an example URL:

Here is a more granular examination of the example above:

URL ComponentsValuesNotes
SchemehttpsNOTE: Non-secure http requests are not supported
Query String?auth-id=123&auth-token=abcAuthentication information, inputs, etc. Additional query string parameters are introduced in the next section.

For additional information about URLs, please read our article about URL components.

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 Request: Supported Methods/Verbs

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 method is supported by this API:

Note: When calling any of our APIs using "Website Key" authentication, only the HTTP GET method is allowed. With "Secret Key" authentication, both HTTP GET and POST methods are allowed.

Send the text with addresses to extract as the body of the request. Set the value of the Content-Type header to text/plain. Each request body is limited to a maximum length of 64 kilobytes. Here's an example POST request submitted using the curl command:

curl -v '
	-H 'Content-Type: text/plain'
	--data-binary '
		There are addresses everywhere.
		1109 Ninth 85007
		SmartyStreets can find them.
		3785 Las Vegs Av.
		Los Vegas, Nevada
		That is all.'

HTTP Request: Input Fields

Along with the body of your POST request (which is the input string from which to extract addresses) there are several other parameters which have an effect on address extraction behavior. These parameters, which are submitted as query string parameters, are detailed in the table below:

htmlderivedHTML input is automatically detected and stripped, but you can manually specify whether your input is formatted as HTML by setting this to true or false.
aggressivefalseAggressive mode may use more lookups on your account, but it can find addresses in populous cities without needing a state and ZIP Code, as well as finding addresses in some messy inputs.
addr_line_breakstrueThis parameter specifies if addresses in your input will ever have line breaks.
addr_per_line0Limits the extractor to a certain number of addresses per input line. Generally, you will not need this parameter unless you are submitting structured data that you know will only have a certain number of addresses per line. Set to 0 (default) for no limit.

HTTP Request: Headers

You must include the following required HTTP headers in all requests:

Content-TypeThe 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: text/plain
HostThe Host request header field specifies the internet host and port number of the resource being requestedHost:

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 CodeResponse and Explanation
401Unauthorized: The credentials were provided incorrectly or did not match any existing, active credentials.
402Payment Required: There is no active subscription for the account associated with the credentials submitted with the request.
400Bad Request (Malformed Payload): The request body was blank or otherwise malformed.
429Too Many Requests: When using public "website key" authentication, we restrict the number of requests coming from a given source over too short of a time. If you use "website key" authentication, you can avoid this error by adding your IP address as an authorized host for the website key in question.
413Request Entity Too Large: The request body was larger than 64 Kilobytes.
200OK (success!): The response body is a JSON object containing metadata about the results and zero or more extracted addresses from the input provided with the request. See the annotated example below for details.

HTTP Response: An Annotated Example

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

curl -v '
	-H 'Content-Type: text/plain'
	--data-binary '
			Meet me at 5732 Lincoln Drive Minneapolis MN

The above sample request yields the following JSON output. NOTE: We have modified the output with // comment statements (which are actually NOT valid JSON) as minimal documentation. Also, it is important to notice that the api_output field has structural parity with the response of the address verification endpoint:

	  // How many total lines of input were received?

	  // Did the text have unicode characters or was it plain ASCII?

	  // How many addresses were found in the input?

	  // How many of the found addresses were valid?

	  // Length of the input in bytes:

	  // Length of the input in characters:

   // Array of addresses extracted from the input.
		 // The actual input text:
         "text":"5732 Lincoln Drive Minneapolis MN",

		 // Was this address verified successfully?

		 // The starting line of the 'text' in the input:

		 // The starting character index of the 'text':

		 // The ending character index of the text:

		 // The actual response from the US Street API:
               "delivery_line_1":"5732 Lincoln Dr",
               "last_line":"Minneapolis MN 55436-1608",

Subscription usage

With the extraction endpoint, the usage on your subscription varies depending on your input. One request to the extraction API will use zero or more lookups on your subscription. Aggressive mode will probably use more lookups, but it may find more addresses.

SSL/TLS Information

Use Modern Security Software and Cipher Suites

Certificate Authority:
	AddTrust External CA Root
	Fingerprint: 02faf3e291435468607857694df5e45b68851868

Supported Protocols:
	TLS 1.2
	TLS 1.1
	TLS 1.0

Cipher Suites: