If you want the ONE question that disproves the theory about the wisdom of the crowd ask 10 000 Lagos dwelling (and possibly all of Nigeria) Nigerians to enter their postcode in a website. An incredible majority would uniformly enter 2341. That could not be further from the truth. 234 1 is the international dialing code to call a Lagos telephone number - oo Nwoye

Postal codes in Nigeria are numeric, consisting of six digits. NIPOST, the Nigerian Postal Service, divides the country into nine regions, which make up the first digit of the code. The second and third digits, combined with the first, are the dispatch district for outgoing sorting.

Well, it is supposed to be that simple. Almost everyone prefer to stick with 2341, which is somewhat correct. Few knows about the post code system . If you’ve ever filled a form on the internet that the postal code field is required, it leaves you clueless sometimes. Most times, I think (as a developer) : Why don’t just make an API call to get this detail. But then, the second question always comes up. From where ? . Yes, From Where ?

I agree with Mark Essien in listing the problems and providing some basic solutions.

  1. Nigerians do not use post codes
  2. Nigerian streets are ambiguous
  3. There is no central way of retrieving all the streets in Nigeria
  4. Street houses are not numbered correctly
  5. You cannot recognize if streets are close to each other
  6. Very long roads cannot be further broken down into pieces (as is possible where post-codes are used)
  7. The post-code allocation system is not expanding as quickly as the country is developing.

An API is created that does the following:

  1. It lists all the streets and houses within a post-code
  2. It can receive an unstructured address, and return a valid address suggestion.
  3. It can provide the GPS location of a particular street at well as the GPS of a particular house number
  4. It provides address suggestions given partial information


Well to do this, you basically need data. Data that only Nipost had access to. Yes, had . I somehow managed to get the data overtime. Kinda wrote a python script that runs periodically, gets details and save on a cloud storage (Google Big Query) . There were some drawback with this.

  1. Nipost has low quota on using Google Api for map.
  2. Small bandwidth.
What is the implication of this:
  1. I have to take into consideration when it starts returning latLng as 0.0,0.0 . Most times, the quota for that days has being exhuasted. Sometimes (rarely), it is just that Nipost does not have the location. I basically have to do the query manually and add it up (A bit stressful but worth it).
  2. Smallbandwidth - I can not run multiple query at same time. It would never return result if I go this route. The site goes down immediately and bounce back a couple of minute later. I had to do some maths, calculate the calls and gently pick the bean.
Why Use Big Query for this ?
  1. Fast ! . It can run petabyte in seconds. Believe me, by the time I finished cloning the data, it was over 20,000 rows. So, to serve it to an audience of developers that would use this, It has to be fast.
  2. Returns result as JSON (smile like you waited for this).
  3. It is relatively cheap for me. I’m making the API open for people to call. I need something cheap (if I am paying at all) to run it.
What the Service Provides.
  1. It lists all the streets within a post-code
  2. It can provide the GPS location of a particular street
  3. It can provide the post-code of areas within a location
  4. It provides address and post-code suggestions given partial information

See example

Using the Service.

Base Url - http://postalstreetdata.appspot.com/api

Fetching details within a location

path - /location

postman_collection - download postman_collection and test using postman

limit - 5

fetching details from partial information

path - /address

postman_collection - download postman_collection and test using postman

limit - 5

fetching details by post code

path - /postcode

postman_collection - download postman_collection and test using postman

limit - 15

Interest and Contributions.

Send me a mail or just drop a comment.

Contributions are welcome. Generally, contributions are managed by issues and pull requests.

Wrapping Up

For issues and suggestions to be followed up, kindly open it on github
Contributions are welcome and I am looking forward to seeing interest on how best this can be.

I would love to know if this article helped anyone and I honestly want to see wonderful stuff it helped you churn out.
Belvi - I Beliv