API Documentation

streetlayer API

Streetlayer offers a straightforward JSON-based REST API service built to analyse and verify international address data by using custom built search algorithms to cross-reference complete addresses (as specified in the API request) as well as each fraction contained therein with a massive, weekly updated and reliable data set sourced from a wide range of vendors and institutions around the world.

Whether your intended use of the API is cleaning your customer database, validating user data at the time it enters your systems, building an address autocomplete system for your web platform or validating high-value contacts or leads with the aim of sending promotional material - regardless of the background or size of your business, you're at the right address.

The following API documentation intends to outline in detail the specifications and features of the API and how they can be made use of using different programmatic approaches and programming languages.


Specs & Overview

API Access Key & Authentication

After signing up, each user is assigned a personal, secret API access key - a unique "password" provided to access any of the API's data endpoints (see API Endpoints) using the HTTP GET method.

To authenticate with the streetlayer API, simply attach your access_key to your preferred endpoint URL:

http://apilayer.net/api/validate?access_key=YOUR_ACCESS_KEY  
                

Get your free API access key


API Endpoints

The streetlayer API offers 3 endpoints, all of which providing different kinds of data and starting out with the following base URL:

http://apilayer.net/api/

There are three available API endpoints - interested in testing them on the spot? Get a free API Access Key »

// "validate" - verify an address
http://apilayer.net/api/validate

// "autocomplete" - get address suggestions based on string  
http://apilayer.net/api/autocomplete    

// "reverse" - get the nearest addresses based on coordinates  
http://apilayer.net/api/reverse     
                

Each API endpoint is explained in detail below in the API Features section.


256-bit HTTPS Encryption
Basic Pro Enterprise

Paid Customers may establish a secure connection (industry-standard SSL) to the streetlayer API and all data provided by and accessible through it.

To connect securely, simply attach an s to the HTTP Protocol. (resulting in https://)


API Error Codes

If your query fails, the streetlayer API will return a 3-digit error-code and a plain text "info" property containing suggestions for the user.

Find below an example error - triggered when a user's monthly API request volume has been reached or exceeded:

{
  "success": false,
  "error": {
    "code": 104,
    "info": "Your monthly usage limit has been reached. Please upgrade your subscription plan."    
  }
}
                


Common API errors:


Code Info [affected API endpoints]
404 "404_not_found" User requested a resource which does not exist.
101 "missing_access_key" User did not supply an access key.
101 "invalid_access_key" User entered an invalid access key.
103 "invalid_api_function" User requested a non-existent API function.
104 "usage_limit_reached" User has reached or exceeded his subscription plan's monthly API request allowance.
105 "function_access_restricted" The user's current subscription plan does not support the requested API Function.

show all errors


JSON Formatting

In order to enhance readability the streetlayer API features a built-in JSON format function, which displays the API's response in typically JSON-structured format.

To enable this function, simply attach format=1 to any valid API endpoint URL:

http://apilayer.net/api/validate
    ? access_key = YOUR_ACCESS_KEY
    [...]
    & format = 1      
                

Please be aware that enabling format increases the API response's file size and should be used for debugging purposes only. Parsing a JSON response in your application may not be possible if the format parameter is in use.


API Features

Address Verification
Free Basic Pro Enterprise

The streetlayer API is capable of verifying international address data in a variety of formats. The address verification feature is available on all subscription plans.

API Request

Making an address verification request is simple - all you need to do is append your API access key to the streetlayer API's validate endpoint and specify the HTTP GET request parameters as per your preference.

Example query:

http://apilayer.net/api/validate
    ? access_key = YOUR_ACCESS_KEY
    & address1 = 767 5th Ave  
    & postal_code = 10153  
    & locality = New York  
    & country_code = USA  
                

Request parameters:

Find below all required and optional API request parameters.


Parameter Description
address1 The first part of the address to be validated. Ideally, this should contain street name and housenumber only.
address2 Additional address parts which that be appended to the final address. In order to achieve the highest possible level of validation, flat numbers, building numbers, housenumber details like "A", names and similar parts should be passed into this request parameter.
address3 Additional address parts which that be appended to the final address. In order to achieve the highest possible level of validation, flat numbers, building numbers, housenumber details like "A", names and similar parts should be passed into this request parameter.
postal_code The postal code value of the address to be validated. Specifying this parameter usually improves validation results significantly.
locality The city value of the address to be validated. Specifying this parameter usually improves validation results significantly.
county Counties are administrative divisions between localities (in most cases, cities) and regions (in most cases, states). Specifying this parameter usually improves validation results significantly.
region Usually the first-level administrative divisions within countries, equivalent to states and provinces in the U.S. and Canada. However, most other countries contain regions as well. Specifying this parameter usually improves validation results significantly.
country_code Additional address parts which will be appended to the final address, but not validated
text The address to be validated in freeform text.


Use of Request Parameters

There are two ways address verification requests can be performed using the API's validate endpoint.

- request using address components:
                
specify address1 AND country_code AND (postal_code OR locality)
                
- freeform text request:

specify text AND country_code
                

As outlined above, if you are using the verification method using address components you will be required to specify at least 3 request parameters. Using the freeform method only 2 parameters are required.


API Response

The API's standard address verification response is an easily parseable JSON file consisting of different objects and properties.

Example response:

{
  "validation_status": "valid",
  "address_components": {
     "country_code_alpha2": "US",
     "country_code_alpha3": "USA",
     "country": "United States",
     "county": "New York County",
     "locality": "New York",
     "postal_code": "10153",
     "region": "New York",
     "street": "5 Avenue",
     "housenumber": "767",
     "neighbourhood": "Midtown"
  },
  "validation_result": {
     "locality": true,
     "county": null,
     "region": null,
     "postal_code": true,
     "street": true,
     "housenumber": true
  },
  "formatted_address": [
     "5 Avenue 767",
     "New York, 10153",
     "United States"
  ],
  "coordinates": {
     "latitude": 40.763554,
     "longitude": -73.972839
  }
}           
                

Find below each of the API's response objects in detail:


Property Description
"validation_status" Returns valid, unsure or invalid depending no whether the requested address could be validated completely (status "valid"), partially (status "unsure"), or not.
"address_components" Contains the requested address separated into its components. Each address component either contains the original value, or - if the API was able to find an improved (corrected) result, a corrected value.
"validation_result" Contains each fragment's validation result. Validation results can be true if the given component could be validated completely, false if the given component could not be validated, or null if the given component was not specified in the request.
"formatted_address" In the event of a successful validation, this response object contains the requested address in its internationally standardized format.
"coordinates" Contains the latitude and longitude coordinates if a complete (status "valid") or partial (status "unsure") validation was performed, or null if the validation failed (status "invalid").


Address Component Validation

When verifying addresses using the API's validate endpoint, the API will also return a validation_result response object containing the validation result of each component of the requested address.

In some cases, provided a given component comes with the value false, the streetlayer API will have corrected the address component in question within the address_components response object.

Taken from the example response above:

  [...]
  "validation_result": {
     "locality": true,
     "county": null,
     "region": null,
     "postal_code": true,
     "street": true,
     "housenumber": true
  },
  [...]
                

Address Formatting

When performing API requests to any of the three available API endpoints, the API's formatted_address response object will contain an internationally formatted version of the requested address.

Taken from the example response above:

  [...]
  "formatted_address": [
     "5 Avenue 767",
     "New York, 10153",
     "United States"
  ],
  [...]
                

Please note: The formatted_address object will only contain reliable data in the event of a successful address validation request.


Geocode

Each API response, regardless of which endpoint you are using, will also contain a coordinates response object with the Latitude and Longitude values for the given address.

Taken from the example response above:

  [...]
  "coordinates": {
     "latitude": 40.763554,
     "longitude": -73.972839
  }
  [...]
                

Interested in finding addresses based on coordinates? Jump to Reverse Lookups »


Address Autocomplete
Free Basic Pro Enterprise

Using the streetlayer API's autocomplete endpoint you will be able to send a freeform text address of any size along with a country code and receive complete address suggestions based on the text specified.

In order to make an autocomplete API request, simply append the text and country_code parameters to your API request and execute your query.

Example query:

http://apilayer.net/api/autocomplete
    ? access_key = YOUR_ACCESS_KEY
    & text = 767 5th A  
    & country_code = USA  
                

Request parameters:

Find below all required and optional API request parameters.


Parameter Description
text The address to be autocompleted in freeform text. required
postal_code Specifying this parameter will restrict autocomplete suggestions to the postal code provided. optional, only available on Pro and Enterprise accounts
country_code The country in which the API should search for the given address. required


API Response

When making requests to the API's autocomplete endpoint, the result set will contain a results array containing address suggestions, each of which coming with an address_components object, a formatted_address object and a coordinates object.

Example response:

{
  "success": true,
  "results": [
     {
        "address_components": {
           "country_code_alpha2": "US",
           "country_code_alpha3": "USA",
           "country": "United States",
           "county": "San Diego County",
           "locality": "Chula Vista",
           "postal_code": "91910",
           "region": "California",
           "street": "5th Avenue",
           "housenumber": "767",
           "neighbourhood": "Mid-Broadway District"
        },
        "formatted_address": [
           "5th Avenue 767",
           "Chula Vista, 91910",
           "United States"
        ],
        "coordinates": {
           "latitude": 32.622941,
           "longitude": -117.081476
        }
     },
     {
        "address_components": {
           "country_code_alpha2": "US",
           "country_code_alpha3": "USA",
           "country": "United States",
           "county": "New York County",
           "locality": "New York",
           "postal_code": "10153",
           "region": "New York",
           "street": "5th Avenue",
           "housenumber": "767",
           "neighbourhood": "Midtown"
        },
        "formatted_address": [
           "5th Avenue 767",
           "New York, 10153",
           "United States"
        ],
        "coordinates": {
           "latitude": 40.763528,
           "longitude": -73.972801
        }
     },
     [...]
                

Please note: The accuracy of the results object ultimately depends on the size and quality of the values contained in the initial request's text parameter.


Autocomplete - Postal Code Boundary
Pro Enterprise

Customers using the Professional or Enterprise Plan may restrict the API's autocomplete suggestions result to a specific postal code by appending the postal_code parameter to an autocomplete API request URL.

Example query:

http://apilayer.net/api/autocomplete
    ? access_key = YOUR_ACCESS_KEY
    & text = 767 5th A  
    & country_code = USA  
    & postal_code = 10153  
                

Autocomplete - Locality Boundary
Pro Enterprise

Customers using the Professional or Enterprise Plan may restrict the API's autocomplete suggestions result to a specific locality (in most cases, city) by appending the locality parameter to an autocomplete API request URL.

Example query:

http://apilayer.net/api/autocomplete
    ? access_key = YOUR_ACCESS_KEY
    & text = 767 5th A  
    & country_code = USA  
    & locality = New York  
                

Reverse Geocode Lookups
Basic Pro Enterprise

The streetlayer API's reverse endpoint allows for the lookup of the nearest addresses based on coordinates. In order to make use of this endpoint, simply append latitude and longitude values to your API request URL.

Example query:

http://apilayer.net/api/reverse
    ? access_key = YOUR_ACCESS_KEY
    & latitude = 40.763528  
    & longitude = -73.972801  
                

Request parameters:

Find below all required and optional API request parameters.


Parameter Description
latitude The latitude value for the reverse lookup request. required
longitude The longitude value for the reverse lookup request. required


API Response

The reverse lookup result set will come with a results array, which contains address suggestion objects ordered from top (most relevant) to bottom (least relevant).

Example response:

{
  "success": true,
  "results": [
     {
        "address_components": {
           "country_code_alpha2": "US",
           "country_code_alpha3": "USA",
           "country": "United States",
           "county": "New York County",
           "locality": "New York",
           "postal_code": "10153",
           "region": "New York",
           "street": "5 Avenue",
           "housenumber": "767",
           "neighbourhood": "Midtown"
        },
        "formatted_address": [
           "5 Avenue 767",
           "New York, 10153",
           "United States"
        ],
        "coordinates": {
           "latitude": 40.763554,
           "longitude": -73.972839
        }
     },
     {
        "address_components": {
           "country_code_alpha2": "US",
           "country_code_alpha3": "USA",
           "country": "United States",
           "county": "New York County",
           "locality": "New York",
           "postal_code": "10022",
           "region": "New York",
           "street": "East 58 Street",
           "housenumber": "12",
           "neighbourhood": "Midtown"
        },
        "formatted_address": [
           "East 58 Street 12",
           "New York, 10022",
           "United States"
        ],
        "coordinates": {
           "latitude": 40.763268,
           "longitude": -73.972842
        }
     },
     
     [...]                
				

Code Examples

PHP (CURL)

Verifying addresses:

Find below an example for how to request the streetlayer to verify an address using PHP:

// set API Access Key
$access_key = 'YOUR_ACCESS_KEY';

// set address parameters
$address1 = '767%205th%20Ave';
$address2 = '';
$address3 = '';
$postal_code = '10153';
$locality = 'New%20York';
$county = '';
$region = '';
$country_code = 'USA';

// Initialize CURL:
$ch = curl_init('http://apilayer.net/api/validate?access_key='.$access_key.'&address1='.$address1.'&address2='.$address2.'&address3='.$address3.'&postal_code='.$postal_code.'&locality='.$locality.'&county='.$county.'®ion='.$region.'&country_code='.$country_code);  
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

// Store the data:
$json = curl_exec($ch);
curl_close($ch);

// Decode JSON response:
$validationResult = json_decode($json, true);

// Access and use your preferred validation result objects
if ($validationResult['validation_status'] == 'valid') {
	
	echo 'Your address verification has been successful. <br> Here is your formatted address: <br><br> ' . $validationResult['formatted_address'][0] . ' <br> ' . $validationResult['formatted_address'][1] . ' <br> ' . $validationResult['formatted_address'][2] . ' <br> ' . $validationResult['formatted_address'][3];    
		
} else if ($validationResult['validation_status'] == 'unsure') {

	echo 'Your address verification has been partially successful.';
	
} else {

	echo 'Your address verification failed.';

}
                

JavaScript (jQuery.ajax)

Verifying addresses:

Find below an example for how to request the streetlayer to verify an address using jQuery.ajax:

// set access key and address parameters
var access_key = 'YOUR_ACCESS_KEY';
var address1 = '767%205th%20Ave';
var address2 = '';
var address3 = '';
var postal_code = '10153';
var locality = 'New%20York';
var county = '';
var region = '';
var country_code = 'USA';

// verify email address via AJAX call
$.ajax({
    url: 'http://apilayer.net/api/validate?access_key=' + access_key + '&address1=' + address1 + '&address2=' + address2 + '&address3=' + address3 + '&postal_code=' + postal_code + '&locality=' + locality + '&county=' + county + '®ion=' + region + '&country_code=' + country_code,   
    dataType: 'jsonp',
    success: function(json) {

    // Access and use your preferred validation result objects
    console.log(json.validation_status);
    console.log(json.address_components);
    console.log(json.formatted_address);
                
    }
});