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);
		}
	});