Getting Started
Introduction
Authentication
Errors
APIs
Useragent API
Postal Code API

Postal Code API Documentation

The Postal Code API provides location details from a zip code including city, state, county, latitude, and longitude.

Calculate the distance between two zip codes and find all zip codes within a specified radius.


API Request

HTTP
http or https
APIKEY
Sign Up or Sign In for API Keys
POSTALCODE
Postal code to lookup.
POSTALCODE2
Second postal code required for distance lookup.
RADIUS
Distance in miles or kilometers, default is miles.
Zip Code to Location
http://postalcode.parseapi.com/api/APIKEY/POSTALCODE
Distance between two Zip Codes
http://postalcode.parseapi.com/api/APIKEY/distance/POSTALCODE/POSTALCODE2
Zip Codes in a radius of a Zip Code
http://postalcode.parseapi.com/api/APIKEY/radius/POSTALCODE/RADIUS

API Response

continent.name string
String representing continent name: Africa, Antarctica, Asia, Europe, North America, Oceania, South America

continent.alpha2 string
String representing continent code: AF, AN, AS, EU, NA, OC, SA

country.name string
String representing country name.

country.alpha2 string
ISO 3166-1 alpha-2 - two-letter country codes which are also used to create the ISO 3166-2 country subdivision codes and the Internet country code top-level domains.

country.alpha3 string
ISO 3166-1 alpha-3 - three-letter country codes which may allow a better visual association between the codes and the country names than the 3166-1 alpha-2 codes.

country.numeric string
ISO 3166-1 numeric – three-digit country codes which are identical to those developed and maintained by the United Nations Statistics Division, with the advantage of script (writing system) independence, and hence useful for people or systems using non-Latin scripts.

country.tld string
Country code top-level domain.

state.name string
String representing state name. Alabama, Alaska, Arizona, California etc...

state.alpha2 string
String representing state code: AL, AK, AZ, CA etc...

county.name string
String representing county name.

city.name string
String representing city name.

code.name string
String representing postal code.

code.latitude string
String representing postal code latitude.

code.longitude string
String representing postal code longitude.

Example Response JSON
{
    "continent": {
        "name": "North America",
        "alpha2": "NA"
    },
    "country": {
        "name": "United States",
        "alpha2": "US",
        "alpha3": "USA",
        "numeric": 840,
        "tld": ".us"
    },
    "state": {
        "name": "North Carolina",
        "alpha2": "NC"
    },
    "county": {
        "name": "Rutherford"
    },
    "city": {
        "name": "Forest City"
    },
    "code": {
        "name": "28043",
        "latitude": "35.32500000",
        "longitude": "-81.84600000"
    }
}

Sample Code

curl
	curl "http://postalcode.parseapi.com/api/APIKEY/28043";
PHP
<?php
	$request = file_get_contents("http://postalcode.parseapi.com/api/APIKEY/28043");
	$data = json_decode($request, true);
	print_r($data);
?>
PHP using curl
<?php
	$ch = curl_init();
	curl_setopt($ch, CURLOPT_URL, "http://postalcode.parseapi.com/api/APIKEY/28043");
	curl_setopt($ch, CURLOPT_RETURNTRANSFER, TRUE);
	$data = curl_exec($ch);
	curl_close($ch);
	
	print_r($data);
?>
Javascript
<script>
	var code = encodeURIComponent('28043');
	var xhr = new XMLHttpRequest();
	xhr.open('GET', 'http://postalcode.parseapi.com/api/APIKEY/'+code, false);
	xhr.send();

	if (xhr.status == 200) {
		var data = JSON.parse(xhr.responseText);
		console.log(data);
	}
</script>
Javascript using jQuery
<script>
	$(document).ready(function() {
		var code = encodeURIComponent('28043');
		$.get('http://postalcode.parseapi.com/api/APIKEY/'+code, function(data) {
			console.log(data);
		});
	});	
</script>
Python
	import requests
	r = requests.get('http://postalcode.parseapi.com/api/APIKEY', params={'code': '28043'})
	data = r.json()
Ruby
	require 'net/http'
	require 'json'
	
	uri = URI('http://postalcode.parseapi.com/api/APIKEY/28043')
	response = Net::HTTP.get(uri)
	JSON.parse(response)
Node.js
	var request = require('request');
	
	var url = 'http://postalcode.parseapi.com/api/APIKEY/28043';
	
	request(url, function (error, response, body) {
		if (!error && response.statusCode == 200) {
			var data = JSON.parse(body);
		}
	});