Skip to content


Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time


PyPI version License Python Versions Build Status Requirements Status

Author:Tasdik Rahman

1   What is it?

Extract meta data like

  • city
  • state
  • county
  • location
    • latitude
    • longitude
  • Appropriate boundaries for that area

by just using the ZIPCODE and Country code

2   Features

  • Written in uncomplicated python

  • Supports all the Country codes specified in the ISO specification i.e all 264 countries where they have a pin code.

    You can find a list of all the country codes at the Wiki page

  • Gives ouput in a dict form or a JSON format

  • Fast and easy to use

3   Installation

3.1   Option 1: installing through pip (Suggested way)

pypi package link

$ pip install pyzipcode-cli

If you are behind a proxy

$ pip --proxy [username:password@]domain_name:port install pyzipcode-cli

Note: If you get command not found then $ sudo apt-get install python-pip should fix that

3.2   Option 2: Installing from source

$ git clone
$ cd pyzipcode-cli/
$ pip install -r requirements.txt
$ python install

4   Usage

4.1   get()

>>> from pyzipcode import Pyzipcode as pz
>>> pz.get(603203, "IN", return_json=True)
  "location": {
    "lat": 12.8336666,
    "lng": 80.0199562
  "city": "Kavanur",
  "state_short": "25",
  "county": "Kanchipuram",
  "state": "Tamil Nadu",
  "postal_code": "603203",
  "bounds": {
    "northeast": {
      "lat": 12.8769479,
      "lng": 80.0572497
    "southwest": {
      "lat": 12.7997355,
      "lng": 79.9504465
  "location_type": "APPROXIMATE",
  "country": "IN"

>>> pz.get(94305, "US", return_json=True)
  "city": "Stanford",
  "country": "US",
  "bounds": {
    "northeast": {
      "lat": 37.44363,
      "lng": -122.1494501
    "southwest": {
      "lat": 37.382743,
      "lng": -122.194849
  "county": "Santa Clara",
  "state": "California",
  "state_short": "CA",
  "postal_code": "94305",
  "location": {
    "lat": 37.4135757,
    "lng": -122.1689284
  "location_type": "APPROXIMATE"

5   To-do

  • [ ] Support timezone extraction
  • [ ] Add cli-support

6   Contributing

Feel free to make a pull request. For that, please refer the Contributing page

7   Bugs

Please report the bugs at the issue tracker

8   Known Issues

  • The zipcodes for Argentina are not working for the release 0.1.3 as reported by DavidVentura on issue #1

9   License :

MIT License © Tasdik Rahman

You can find a copy of the License at

10   Donation

If you have found my little bits of software being of any use to you, do consider helping me pay my internet bills :)

Paypal badge