:globe_with_meridians: A Python wrapper for the Geocodio geolocation service API

Overview

Py-Geocodio

https://travis-ci.org/bennylope/pygeocodio.svg?branch=master

Python wrapper for Geocodio geocoding API.

Full documentation on Read the Docs.

If you are upgrading from a version prior to 0.2.0 please see the changelog in HISTORY.rst. The default coordinate ordering has changed to something a bit more sensible for most users.

Geocodio API Features

  • Geocode an individual address
  • Batch geocode up to 10,000 addresses at a time
  • Parse an address into its identifiable components
  • Reverse geocode an individual geographic point
  • Batch reverse geocode up to 10,000 points at a time
  • Perform operations using the HIPAA API URL

The service is limited to U.S. and Canada addresses for the time being.

Read the complete Geocodio documentation for service documentation.

Installation

pygeocodio requires requests 1.0.0 or greater and will ensure requests is installed:

pip install pygeocodio

Basic usage

Import the API client and ensure you have a valid API key:

>>> from geocodio import GeocodioClient
>>> client = GeocodioClient(YOUR_API_KEY)

Geocoding

Geocoding an individual address:

>>> geocoded_location = client.geocode("42370 Bob Hope Drive, Rancho Mirage CA")
>>> geocoded_location.coords
(33.738987255507, -116.40833849559)

Batch geocoding

You can also geocode a list of addresses:

>>> geocoded_addresses = client.geocode([
        '2 15th St NW, Washington, DC 20024',
        '3101 Patterson Ave, Richmond, VA, 23221'
    ])

Return a list of just the coordinates for the resultant geocoded addresses:

>>> geocoded_addresses.coords
[(38.890083, -76.983822), (37.560446, -77.476008)]
>>> geocoded_addresses[0].coords
(38.890083, -76.983822), (37.560446, -77.476008)

Lookup an address by the queried address:

>>> geocoded_addresses.get('2 15th St NW, Washington, DC 20024').coords
(38.879138, -76.981879))

Address parsing

And if you just want to parse an individual address into its components:

>>> client.parse('1600 Pennsylvania Ave, Washington DC')
  {
      "address_components": {
          "number": "1600",
          "street": "Pennsylvania",
          "suffix": "Ave",
          "city": "Washington",
          "state": "DC"
      },
      "formatted_address": "1600 Pennsylvania Ave, Washington DC"
  }

Reverse geocoding

Reverse geocode a point to find a matching address:

>>> location = client.reverse((33.738987, -116.4083))
>>> location.formatted_address
"42370 Bob Hope Dr, Rancho Mirage CA, 92270"

Batch reverse geocoding

And multiple points at a time:

>>> locations = client.reverse([
        (33.738987, -116.4083),
        (33.738987, -116.4083),
        (38.890083, -76.983822)
    ])

Return the list of formatted addresses:

>>> locations.formatted_addresses
["42370 Bob Hope Dr, Rancho Mirage CA, 92270",  "42370 Bob Hope Dr, Rancho Mirage CA, 92270", "2 15th St NW, Washington, DC 20024"]

Access a specific address by the queried point tuple:

>>> locations.get("38.890083,-76.983822").formatted_address
"2 15th St NW, Washington, DC 20024"

Or by the more natural key of the queried point tuple:

>>> locations.get((38.890083, -76.983822)).formatted_address
"2 15th St NW, Washington, DC 20024"

CLI usage

In the works!

Documentation

For complete documentation see the docs.

License

BSD License

Comments
  • Getting more than one field to return information

    Getting more than one field to return information

    In playing around with this wrapper, I tried to pull all of the fields available when geocoding an address. Heres my code:

    r = '42370 Bob Hope Dr, Rancho Mirage CA' geocoded_location = client.geocode(r, fields=['cd','school'] )

    This returns the 'school' attribute of fields, but not the 'cd'. I'd like to be able to pass more than one field and this doesn't not support this capability.

    I would try to fix this myself, but I am not skilled enough in python.

    Thanks.

    opened by ccdpowell 7
  • Updated batch_geocode for dictionaries

    Updated batch_geocode for dictionaries

    This addresses #27

    This is admittedly a very blunt approach to the problem: LocationCollectionDict is a version of LocationCollection that inherits from dictionary instead of list.

    The batch geocoder endpoint for geocod.io accepts a JSON object. Currently batch_geocode only accepts lists of addresses. When a python dictionary of keys and addresses is passed to batch_geocode, the geocod.io interprets it as a JSON object and returns a JSON object in its response. The results field is now a JSON object rather than an array, which python interprets as a dictionary.

    LocationCollection expects a list from response.json()["results"] and understandably breaks. If the response is instead a dictionary, it gets rerouted to LocationCollectionDict to create a comparable dictionary object. LocationCollectionDict changes the list methods in LocationCollection to dictionary methods

    opened by liufran1 3
  • KeyError

    KeyError

    I get KeyErrors when I run the last two examples in the README https://github.com/bennylope/pygeocodio

    locations.get("33.738987, -116.4083").formatted_address and locations.get((33.738987, -116.4083)).formatted_address

    help-wanted documentation 
    opened by mroswell 3
  • No longer keeping client-side field whitelist

    No longer keeping client-side field whitelist

    This moves the responsibility of validating field names to the server instead of the client.

    In practice, this lets users request newer fields such as census2010, and ensures that the list in the library will not need to be continuously updated.

    opened by MiniCodeMonkey 2
  • Feature/add components search

    Feature/add components search

    Related to: #30

    Changes:

    • Give geocode(...) 2 parameters: address_data + components_data
      • If both are populated or both are empty, nothing happens
      • If addres_data is provided (default first parameter), searching behaves like previusly
      • If comonents_data is a single dict or list of dicts populated with the supported fields here, geocoding occurs with components as the parameters instead of the freeform address string
    • You can lookup a result based on the address components geocoded
    opened by Unix-Code 2
  • Including a reference key in batch encoding

    Including a reference key in batch encoding

    Geocodio batch encoding allows for a reference key to be included if the request is submitted as a JSON object rather than a JSON array. See https://www.geocod.io/docs/#batch-geocoding

    Can this functionality be added?

    enhancement 
    opened by arashrez 2
  • Update to API v1.3

    Update to API v1.3

    • Update client
    • Update test client

    v1.3 (Released on March 12th, 2018)

    timezone appends:

    Breaking: name property has been renamed to abbreviation name is now the full timezone name in a tzdb-compatible format.

    opened by joshgeller 2
  • Broken __init__.py and client.py in pip package manager

    Broken __init__.py and client.py in pip package manager

    Hello there,

    It looks like this commit did not make it to the pip package manager. geocodio/init.py is still using the outdated format and client.py is still using version 1 of the Geocodio API: https://github.com/bennylope/pygeocodio/commit/9631d11da62f6e9a205a3b7430e34c556c601592

    I am more than happy to do any testing, George

    bash-3.2$ pip install geocodio Collecting geocodio Requirement already satisfied: Requests>=2.2.0 in ./anaconda/lib/python3.6/site-packages (from geocodio) Requirement already satisfied: idna<2.7,>=2.5 in ./anaconda/lib/python3.6/site-packages (from Requests>=2.2.0->geocodio) Requirement already satisfied: chardet<3.1.0,>=3.0.2 in ./anaconda/lib/python3.6/site-packages (from Requests>=2.2.0->geocodio) Requirement already satisfied: urllib3<1.23,>=1.21.1 in ./anaconda/lib/python3.6/site-packages (from Requests>=2.2.0->geocodio) Requirement already satisfied: certifi>=2017.4.17 in ./anaconda/lib/python3.6/site-packages (from Requests>=2.2.0->geocodio) Installing collected packages: geocodio Successfully installed geocodio-1.0.1

    bash-3.2$ python3.6 Python 3.6.1 |Anaconda 4.4.0 (x86_64)| (default, May 11 2017, 13:04:09) [GCC 4.2.1 Compatible Apple LLVM 6.0 (clang-600.0.57)] on darwin Type "help", "copyright", "credits" or "license" for more information.

    from geocodio import GeocodioClient Traceback (most recent call last): File "", line 1, in File "anaconda/lib/python3.6/site-packages/geocodio/init.py", line 8, in from client import Client ModuleNotFoundError: No module named 'client'

    exit()

    cat anaconda/lib/python3.6/site-packages/geocodio/init.py

    !/usr/bin/env python
    -*- coding: utf-8 -*-
    
    __author__ = 'David Stanley'
    __email__ = '[email protected]'
    __version__ = '1.0.0'
    
    from client import Client
    
    __all__ = [Client]
    

    bash-3.2$ head anaconda/lib/python3.6/site-packages/geocodio/client.py

    import requests, json
    
    class Client:
        url = 'http://api.geocod.io/v1'
        api_key = ''
    
        def __init__(self, api_key):
            """ Initialize the class, setting the api_key to the class property """
            self.api_key = api_key
    
    opened by georgezoto 2
  • How to extract LAT and LON separately from geocoded_location.coords?

    How to extract LAT and LON separately from geocoded_location.coords?

    Hopefully an easy question, but is it possible to get a separate value for LON/X AND LAT/Y from the geocoded_location.coords object?

    We're testing how, using python, the output coordinates can be dumped into a PostGIS database and assembled into a geometry object.

    Thanks!

    opened by dpsspatial 2
  • README errors

    README errors

    The README example uses the coordinate (33.738987, -116.408) and mis-states the results in various places as '1600 Pennsylvania Ave, Washington, DC' or '100 Main St, Springfield, USA'

    Someone needs to review the README pretty carefully. (I'm hoping that a careful proofing will also yield an answer to #9 )

    help-wanted documentation 
    opened by mroswell 2
  • Field name

    Field name "census" raises a ValueError

    "census" is one of the available fields: https://geocod.io/docs/#census-block-tract-amp-fips-codes, but calling client.geocode(address, fields=['census']) raises a ValueError ("census' is not a valid field value"). I fixed this locally by adding 'census' to ALLOWED_FIELDS on line 15 of client.py.

    opened by ndingwall 2
Releases(v1.0.1)
Owner
Ben Lopatin
I leverage synergies.
Ben Lopatin
Twitter-bot - A Simple Twitter bot with python

twitterbot To use this bot, You will require API Key and Access Key. Signup at h

Bentil Shadrack 8 Nov 18, 2022
Checks instagram names to see if they're available

How to install You must have python 3.7.6 installed and make sure you click the 'ADD TO PATH' option when installing Open cmd and type pip install aio

2 Oct 20, 2021
Converts a text file of songs to a playlist on your Spotify account.

Playlist Converter Convert a text file of songs to a playlist on your Spotify account. Create your playlists faster instead of manually searching for

Priya Aggarwal 18 Dec 21, 2022
Code for generating Tiktok X-Gorgon, X-Khronos and etc. parameters

TikTok-Algorithm I found this python file from a source which was later deleted. Although the test api functions no longer seem to work, surprisingly

0 Dec 09, 2021
Change your discord avatar every x h/d based on a list of images

Discord-Avatar-Autochange Introduction A simple script that automatically keeps changing your discord avatar after a given amount of time based on the

Armin Amiri 5 Apr 30, 2022
Source code from thenewboston Discord Bot with Python tutorial series.

Project Setup Follow the steps below to set up the project on your environment. Local Development Create a virtual environment with Python 3.7 or high

Bucky Roberts 24 Aug 19, 2022
Auxiliator is telegram bot for basic web-application analysis

Auxiliator Auxiliator is telegram bot for basic web-application analysis What for? Sometimes there is no access to your main PC, where you can scan we

Revoltage 13 Dec 26, 2021
DB-Drive-CSV - This is app is can be used to access CSV file as JSON from Google Drive.

DB Drive CSV This is app is can be used to access CSV file as JSON from Google Drive. How To Use Create file/ upload file to Google Drive There's 2 fi

Hartawan Bahari M. 5 Oct 20, 2022
Discord nuke bot with python

Discord-nuke-bot 🇷🇺 🇷🇺 🇷🇺 🇷🇺 🇷🇺 TODO: Добавить команду: Удаления всех ролей Спама каналами Спама во все каналы @everyone Удаления всего aka

Nikita Maykov 10 Oct 14, 2022
BoostIRC - IRC Bot which posts boosts to IRC

BoostIRC Quick Start git clone https://github.com/valcanobacon/BoostIRC.git cd B

7 Dec 23, 2022
Telegram bot which has truecaller and smsbomber features

Truecaller-telegram_bot Add your telegram bot api key in main.py and you are good to go To get a api key Goto telegram and search BotFather From the c

Rudranag 32 Dec 05, 2022
企业微信消息推送的python封装接口,让你轻松用python实现对企业微信的消息推送

👋 corpwechat-bot是一个python封装的企业机器人&应用消息推送库,通过企业微信提供的api实现。 利用本库,你可以轻松地实现从服务器端发送一条文本、图片、视频、markdown等等消息到你的微信手机端,而不依赖于其他的第三方应用,如ServerChan。 如果喜欢该项目,记得给个

Chaopeng 161 Jan 06, 2023
Low-level, feature rich and easy to use discord python wrapper

PWRCord Low-level, feature rich and easy to use discord python wrapper Important Note: At this point, this library API is considered unstable and can

MIguel Lopes 1 Dec 26, 2021
A GUI Application that creates a Spotify Playlist from any year in the past, by just entering your preferred date

A GUI Application that creates a Spotify Playlist from any year in the past, by just entering your preferred date

David .K. Danso 1 Jan 17, 2022
Scuttlecrab.py - Python Version of Scuttle Crab Bot

____ _ _ _ ____ _ / ___| ___ _ _| |_|

Fabrizo 4 Jul 08, 2022
A module to complement discord.py that has Music, Paginator and Levelling.

discord-super-utils A modern python module including many useful features that make discord bot programming extremely easy. Features Modern leveling m

Yash 106 Dec 19, 2022
Actively maintained, pure Python wrapper for the Twitter API. Supports both normal and streaming Twitter APIs.

Twython Twython is a Python library providing an easy way to access Twitter data. Supports Python 3. It's been battle tested by companies, educational

Ryan McGrath 1.9k Jan 02, 2023
StringSessionGenerator - A Telegram bot to generate pyrogram and telethon string session

⭐️ String Session Generator ⭐️ Genrate String Session Using this bot. Made by TeamUltronX 🔥 String Session Demo Bot: Environment Variables Mandatory

TheUltronX 1 Dec 31, 2021
PyFacebook

== PyFacebook == PyFacebook is a Python client library for the Facebook API. Samuel Cormier-Iijima ( Samuel Cormier-Iijima 573 Dec 20, 2022

A Telegram AntiChannel bot to ban users who using channel to send message in group

Anti-Channel-bot A Telegram AntiChannel bot to ban users who using channel to send message in group. BOT LINK: Features: Automatic ban Whitelist Unban

Jigar varma 36 Oct 21, 2022