Sepomex
Sepomex is a REST API that maps all the data from the current zip codes in Mexico. You can get the CSV or Excel files from the official site
We build this API in order to provide a way to developers query the zip codes, states and municipalities across the country.
Table of contents
Quick start
The base URI to start consuming the JSON response is under:
https://sepomex-api.herokuapp.com/api/v1/
There are currently 145,481
records on the database which were extracted from the CSV file included in the project.
Records are paginated with 50 records per page.
Running the project
Prerequisites
- Install the
foreman
gem with:
% gem install foreman
To run the api locally you can follow the next steps:
- First clone the project
git clone https://github.com/IcaliaLabs/sepomex.git
- Run the
bin/setup
script - Lift the server
foreman start
Or by hand
- First clone the project
git clone https://github.com/IcaliaLabs/sepomex.git
- Under the
sepomex
directory run thebundle install
command to download all the dependencies - Set up the
database.yml
to meet your requirements and create it - Migrate the database,
rake db:migrate
- We have provided a rake task to migrate the CSV data:
rake db:migrate:zip_codes
- Lift the server
foreman start
Querying the API
We currently provide 3 kind of resources, zip_codes, states and municipalities:
ZipCodes | States | Municipalities |
---|---|---|
https://sepomex-api.herokuapp.com/api/v1/zip_codes | https://sepomex-api.herokuapp.com/api/v1/states | https://sepomex-api.herokuapp.com/api/v1/municipalities |
ZipCodes
In order to provide more flexibility to search a zip code, whether is by city, colony, state or zip code you can now send multiple parameters to make the appropiate search. You can fetch the:
by city
curl -X GET https://sepomex-api.herokuapp.com/api/v1/zip_codes -d city=monterrey
by state
curl -X GET https://sepomex-api.herokuapp.com/api/v1/zip_codes -d state=nuevo%20leon
by colony
curl -X GET https://sepomex-api.herokuapp.com/api/v1/zip_codes -d colony=punta%20contry
by cp
curl -X GET https://sepomex-api.herokuapp.com/api/v1/zip_codes -d zip_code=67173
all together
curl -X GET https://sepomex-api.herokuapp.com/api/v1/zip_codes \
-d colony=punta%20contry \
-d state=nuevo%20leon \
-d city=guadalupe
Note: A link for the json attributes description is provided here
States
The states
resources can be fetch through several means:
all
curl -X GET https://sepomex-api.herokuapp.com/api/v1/states
by id
curl -X GET https://sepomex-api.herokuapp.com/api/v1/states/1
states municipalities
curl -X GET https://sepomex-api.herokuapp.com/api/v1/states/1/municipalities
Municipalities
all
curl -X GET https://sepomex-api.herokuapp.com/api/v1/municipalities
by id
curl -X GET https://sepomex-api.herokuapp.com/api/v1/municipalities/1
by zip_code
curl -X GET https://sepomex-api.herokuapp.com/api/v1/municipalities -d zip_code=67173
Contributing
Please submit all pull requests against a separate branch.
Code of conduct
This project adheres to the Contributor Covenant 1.2. By participating, you are expected to honor this code.
Heroes
Abraham Kuri
Copyright and license
Code and documentation copyright 2013-2015 Icalia Labs. Code released under the MIT license.