Overview

The Postal Address API is a HTTP based API that you can use to programmatically query physical addressing data held in our database. The Postal Address API works with any programming language that has HTTP library.

  1. The Postal Code
  2. Sample Address
  3. Postal Zones
  4. Common Scenarios

The Postal Code

A postal code for those unfamiliar with the word helps to identify a physical street address in a simple short code. Our postal code developed as part of our Postal Addressing System (Patent Pending: GB1408969.2) is an alphanumeric code that follows the following format:

AANN NNNAA

A = ISO basic Latin alphabet A-Z

N = Numeral 1 to 9

The postal code identifies the Postal Zone, Postal Sector, Postal Area and a Postal Street of a region in a country.

postalcode format

Possible Postal Code formats are:

AANN NNNAA | AANN NNAA | AAN NNNAA | AAN NNAA


Case Project: Kenya

Given a postal code NB16 22KS for Kimathi Street in Nairobi Kenya, the units of the postal code would identify

  • NB as the Postal Zone Code of NAIROBI county,
  • 16 as the Postal Sector Code of STAREHE sub-county,
  • 2 as the Postal Area Code of NAIROBI CENTRAL ward,
  • 2 as the Street Code Differentiator for street name KIMATHI STREET and
  • KS as the Street Code for KIMATHI STREET located within NAIROBI CENTRAL Postal Area boundaries.

As a developer you can query every element of the postal code in the PostCodeFX database using the Postal Address API to provided you with postal address data associated with it.

HOST https://www.postcodefx.com
GET /api?rqst=search_address&q=NB16 22KS&key=YOUR_API_KEY
OR
/api?rqst=search_address&q=Kimathi Street Nairobi&key=YOUR_API_KEY

JSON Response

{ "response":"success", "postalAddress" : [ { "postalStreet" : "KIMATHI STREET", "postalArea" : "NAIROBI CENTRAL", "postalZone" : "NAIROBI", "postalCode" : "NB16 22KS", "lat" : "0.0", "lng" : "0.0" } ] }

Postal Zones

County Name Code
1 BARINGO BR
2 BOMET BM
3 BUNGOMA BG
4 BUSIA BS
5 ELGEYO MARAKWET EM
6 EMBU EB
7 GARISSA GR
8 HOMA BAY HB
9 ISIOLO SL
10 KAJIADO KJ
11 KAKAMEGA KK
12 KIAMBU KA
13 KILIFI KL
14 KERICHO KR
15 KIRINYAGA KG
16 KISII KS
17 KISUMU KM
18 KITUI KT
19 KWALE KW
20 LAIKIPIA LK
21 LAMU LM
22 MACHAKOS MK
23 MAKUENI MN
24 MANDERA MD
25 MARSABIT MT
26 MERU ME
27 MIGORI MG
28 MOMBASA MB
29 MURANGA MA
30 NAIROBI NB
31 NAKURU NK
32 NANDI ND
33 NAROK NR
34 NYAMIRA NM
35 NYANDARUA NA
36 NYERI NY
37 SAMBURU SB
38 SIAYA SY
39 TAITA TAVETA TT
40 TANA RIVER TR
41 THARAKA NITHI TN
42 TRANS NZOIA TZ
43 TURKANA TK
44 UASIN GISHU UG
45 VIHIGA VH
46 WAJIR WJ
47 WEST POKOT WP

Common Scenarios

There are many scenarios that you can use the Postal Address API to solve problems or to supplement other data. The Postal Address API has several resources that can be used in many ways to build solutions solving many logistic or location problems.

Here are some scenarios where The Postal Address API can be useful:

What is My Address

For a delivery company to locate a customer address, they would ask the customer to provide a precise description of their physical location. In this scenario a search form could be provided where a customer would enter the name of their street and county or If they know their postal code (as provided by postcodefx) they would enter the postal code and a precise address would be returned. If a partial postal code is entered a list of addresses would be returned in response, then the customer would choose their exact address from the list.


Resources you can use

Get Postal Address Record

Request {postalCode}

HOST https://www.postcodefx.com
GET /api?rqst=postal_address_record&postalcode=NB16 22KS&key=YOUR_API_KEY

Search Postal Address

Request {General Search}

HOST https://www.postcodefx.com
GET /api?rqst=search_address
&q={full or partial postalcode | street and county name}
For example: q=NB16 22KS OR q=NB16 2 OR search=Kimathi Street Nairobi
&key=YOUR_API_KEY

JSON Response

{ "response":"success", "streetAddress" : [ { "postalStreet" : "KIMATHI STREET", "postalArea" : "NAIROBI CENTRAL", "postalZone" : "NAIROBI", "postalCode" : "NB16 22KS", "lat" : "0.0", "lng" : "0.0" } ] }

What is My Postal Code

To identify a postal code for a named street, you supply the name of street and its county, and a result of one or more addresses would be returned.


Resource to use
HOST https://www.postcodefx.com
GET /api?rqst=search_address&q=Kimathi Street Nairobi&key=YOUR_API_KEY

JSON Response

{ "response":"success", "postalAddress" : [ { "postalStreet" : "KIMATHI STREET", "postalArea" : "NAIROBI CENTRAL", "postalZone" : "NAIROBI", "postalCode" : "NB16 22KS", "lat" : "0.0", "lng" : "0.0" } ] }