Address Validation API with streetlayer

There is so much of our web and eCommerce that consumers take for granted: payment types and validation, exchange rates, etc.  One of the aspects of eCommerce that should be a given, from both a developer and consumer perspective, is address handling.  We'd like to think the consumer enters their address correctly but the risk is if the don't that their experiences gets ruined by the shipping company not finding the address or, worse yet, a situation where the package is lost and you need to incur a loss shipping them another item (assuming you'd prefer to avoid a contentious fight with the consumer about whose fault the problem is).

Of course eCommerce isn't the only reason for address validation and lookup.  You may want coordinates to load a Google Map, you may want to get the user's county, you may want to get zip code information for sales tax calculation -- the use cases are endless.  streetlayer is the service than can perform all address validation needs.

Quick Hits

• The streetlayer API is super easy to use
• Get address validation, autocompletion, and geocoding
• Provides international address information
• streetlayer allows JSONP requests
• Provides HTTPS API usage
• Clear documentation and code samples
• Very competitive pricing

Using streetlayer

streetlayer offers free signup with a generous request allotment for testing.  After you sign up you'll be given an API key to begin development.  Let's have a look at the different ways you can use streetlayer!

streetlayer Usage Tips

A few constants when using the streetlayer API:

• All requests are GET requests
• All requests require an access_key key/value parameter for the API key
• Adding format=1 to the query string for streetlayer to indent the JSON response

Validating an Address

Validating an address is the most common use of address APIs.  Trusting consumers to input information (outside of payment, which is instantly verifiable) can lead to trouble.  If you're going to verify payment information, why wouldn't you verify delivery address information if you can?

Once your customer provides your web or native app with their address information, the first step should be verifying that information, as it's an easy HTTP request to save you shipping and billing trouble down the road.  Shoot their given address information to streetlayer with one simple request:

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

In the case of address verification from streetlayer, you'll see the following 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
  }
}

Note the validation_status key's value of verified -- that confirms that the address is verified as correct.  If an address cannot be verified, you'll see a unsure value.

Autocompleting an Address

In the case that you receive a partial address, or the initial address information isn't verified and you want to suggest a verified address with less information, streetlayer lets you do that:

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

{
  "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
        }
     },
     [...]

Presenting a different, verified address to users if their address information is unverified is commonplace and very useful -- a sign to the customer or user that they can no problems their transaction.

Get Address by Coordinates (Reverse Geocode Lookup)

I've focused much of this post on eCommerce but address services like streetlayer have much more utility.  For example, think about retrieving approximate addresses by coordinates.  Why coordinates?  Think about EXIF data from a photo; you can use EXIF coordinate data to find and approximate address of a photo:

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

{
  "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
        }
     },
     
     [...]                

From those coordinates streetlayer provides the approximate address!

True story:  in my first year as a professional web developer, a client was blaming my employer for her eCommerce site's shipments not always making it to customers.  At the time, there was no streetlayer-like service, so we were relying on customers to properly enter information...and it led to me getting angry phone calls.  In the end, streetlayer address verification has the potential to save yourself and your customers from shipment, identity, and other geolocation problems!