: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
A powerful, cool and well-made userbot for your Telegram profile with promising extension capabilities.

Telecharm userbot A powerful, fast and simple Telegram userbot written in Python 3 and based on Pyrogram 1.X. Currently in active WIP state, so feel f

Daniil Kovalenko 16 Dec 01, 2022
An App to get Ko-Fi payment updates on Telegram.

Deployments. Heroku.com 🚀 Replit.com 🌀 Make sure your app runs 24*7 Zeet.co 💪 Use this :~ Get Bot token from @botfather 🤖 Get ID where you want to

Jainam Oswal 16 Nov 12, 2022
A Python module for communicating with the Twilio API and generating TwiML.

twilio-python The default branch name for this repository has been changed to main as of 07/27/2020. Documentation The documentation for the Twilio AP

Twilio 1.6k Jan 05, 2023
Td-Ameritrade, Tradingview, Webhook, AWS Chalice

TDA-Autobot TDA-Autobot is an automated fire and forget trading mechanism utilizing Alex Golec's(Author) tda-api wrapper, Tradingview webhook alerts,

Kyle Jorgensen 2 Dec 12, 2021
pokemon-colorscripts compatible for mac

Pokemon colorscripts some scripts to print out images of pokemons to terminal. Inspired by DT's colorscripts compilation Description Prints out colore

43 Jan 06, 2023
historical code from reddit.com

This repository is archived. This repository is archived and will not receive any updates or accept issues or pull requests. To report bugs in reddit.

The Reddit Archives 16.3k Dec 31, 2022
Based Telegram Bot and Userbot To Play Music in Your Telegram Groups With Some Cool Extra Features! 🥰

CallMusicPlus69 This Repo base on! 🤗️ A CallsMusic Based Telegram Bot and Userbot To Play Music in Your Telegram Groups With Some Cool Extra Features

brut✘⁶⁹ // ユスフ 6 Jun 26, 2022
Manage AWS Secrets the easy way

AWStanding Easily load variables from AWS Parameter store into environment variables. Why to AWStanding? Because it handles AWS pagination so the amou

Juan Ignacio Sánchez Sampayo 13 Dec 30, 2022
AuthGG is a Python library for dealing with Auth.gg apis

AuthGG AuthGG is a Python library for dealing with Auth.gg apis Installation Use the package manager pip to install requests Add the auth.py file in y

ExtremeDev 1 Dec 20, 2021
WikipediaBot from mohirdev.uz

wiki-bot WikipediaBot from mohirdev.uz Requirements wikipedia aiogram Installing wiki/aiogram pip install wikipedia pip install aiogram

Muhammad Ali 5 Sep 28, 2022
This is a open source discord bot project

pythonDiscordBot This is a open source discord bot project #based on the MAX A video: https://www.youtube.com/watch?v=jHZlvRr9KxM Prerequisites Python

Edson Holanda Teixeira Junior 3 Oct 11, 2021
A Slash Commands Discord Bot created using Pycord!

Hey, I am Slash Bot. A Bot which works with Slash Commands! Prerequisites Python 3+ Check out. the requirements.txt and install all the pakages. Insta

Saumya Patel 18 Nov 15, 2022
An open souce video/music streamer based on MPV and piped.

🎶 Harmony Music An easy way to stream videos or music from Youtube from the command line while regaining your privacy. 📖 Table Of Contents ❔ What's

Zingy Tomato 16 Nov 15, 2022
A Discord Server Cloner With Lot Of New Features.

Technologies Screenshots Table of contents About Installation Links Deployed Features Website Score Contribution Need Help? Instagram Discord About A

NotSakshyam 25 Dec 31, 2022
Alcarin Tengwar - a Tengwar typeface designed to pair well with the Brill typeface

Alcarin Tengwar Alcarin Tengwar is a Tengwar typeface designed to pair well with

Toshi Omagari 23 Nov 02, 2022
A small discord bot to interface with python-discord's snekbox.

A small discord bot to interface with python-discord's snekbox.

Hassan Abouelela 0 Oct 05, 2021
A Sublime Text plugin that displays inline images for single-line comments formatted like `// ![](example.png)`.

Inline Images Sometimes ASCII art is not enough. Sometimes an image says more than a thousand words. This Sublime Text plugin can display images inlin

Andreas Haferburg 8 Jul 01, 2022
Add Reactions to your Channel Posts!

• Shaaak - Post Reaction Bot Simple and Minimalistic telegram bot to add Reactions and Comments to your Channel Posts! - What's Unique About it?

Harsh Raj 4 Jan 31, 2022
Raid ToolBox (RTB) is a big toolkit of Spamming/Raiding/Token management tools for discord.

This code is very out of date and not very good, feel free to make it into something better. (we check the github page every 5 years to pulls your PRs

2 Oct 03, 2021
Probably Overengineered Unimore Booker

POUB Probably Overengineered Unimore Booker A python-powered, actor-based, telegram-facing, timetable-aware booker for unimore (if you know more adjec

Lorenzo Rossi 3 Feb 20, 2022