Table of contents

Mexico Postal codes API with Django

Mexico Postal codes API with Django

Do you need to get the data associated with a postal code in Mexico for your Django application? I wrote a small library called django-postalcodes-mexico that downloads postal codes from SEPOMEX (México’s Postal Codes official site) and creates an API endpoint that allows you to query a postal code in Mexico and receive the colonias that belong to that postal code, as well as their state and municipality.

If you are going to develop a REST API, I have a post with multiple REST API design recommendations that may help you.

For this example I use Python 3.8, Django 3.2.5 and Pipenv version 2020.5.28.


To install it we are going to use Pipenv, but you can use Poetry, pip or any other virtual environment manager.

pipenv shell
pipenv install django-postalcodes-mexico django
django-admin startproject codigosPostalesMx .
python migrate

Next we install the package by adding it to INSTALLED_APPS in our configuration file.


We execute the migrations. This will create the tables needed to manage the postal codes.

python migrate

Obtaining Mexico’s postal codes from SEPOMEX

Now that the tables have been created we are going to install the Mexico postal codes directly from the SEPOMEX page with a single Django command.

python importpostalcodesmx
Trying to connect to Mexican Postal Service (Correos de Mexico)
Response received
This process can take a few minutes, please be patient
Creating database...
The postal code database has been successfully populated

That’s all, now we just need to import include and add our urls. I put the path api/ but you can use the one you want.

from django.contrib import admin
from django.urls import path, include

from django_postalcodes_mexico import urls as django_postalcodes_mexico_urls

urlpatterns = [
    # ...
    path('api/', include(django_postalcodes_mexico_urls)),

Obtaining information from a postal code

If we now make a request api/09000/ or any other 5-digit postal code we will receive a JSON response with the municipality, state and a list of neighborhoods.

curl localhost:8000/api/09000/
{"codigoPostal": "09000", "municipio": "Iztapalapa", "estado": "Ciudad de M\u00e9xico", "colonias": ["La Asunci\u00f3n", "San Ignacio", "San Jos\u00e9", "San Lucas", "San Pablo", "San Pedro", "Santa B\u00e1rbara"]}

Django API query result for postal code “09000”
Django API query result for postal code 09000

A non-existent postal code will return a 404 status.

Nonexistent postal code returning an error message
Nonexistent postal code returning an error message

While an invalid postal code will return a 400 error and an error message

Invalid postal code returning an error
Invalid postal code returning an error

Read the short official documentation in my github repository for more information.

Eduardo Zepeda
Web developer and GNU/Linux enthusiast always learning something new. I believe in choosing the right tool for the job and that simplicity is the ultimate sophistication. I'm under the impression that being perfect is the enemy of getting things done. I also believe in the goodnesses of cryptocurrencies outside of monetary speculation.
Read more