places-geocode 0.2.6

Package for Places Geocoding API service

Places API Geocoding!

There are a many geocoding APIs out there to choose from. However, Places API tops them all with the most accurate, affordable, and effective solution!

Our package focuses on a pythonic and accessible way to geocode POIs (Places of Interest) in Python.

---

SUPPORT

We have multiple support channels that you can contact us on:

• Slack
• Twitter

---

NOTE

Places is a commercial product created for the purpose of geocoding with simplicity and speed. Authorization API tokens are necessary for using the API endpoints. Registering such API tokens is possible through our website subscription page.

→ Check out our official documentation!

---

QUICK START

The places module:

The places(token: str) module allows you to register your access tokens into the Places API which provides the base functionality for geocoding, density, convex, and radius calls.

→ Note: The Places API package undergoes constant development so consider that endpoint changes may occur.

To import the Places API package:

from places_geocode import places_api as pa

---

TABLE OF CONTENTS

Endpoint	Function
load_properties_api	load_radius()
convex_search	convex()
density_search	density()
reverse_geocode	reverse()
batch_reverse	batch_reverse()
geocode	forward()
batch_geocode	batch_forward()

---

API EXAMPLES

All example code to the Places API package can be found below:

load_radius()

• coordinate: required, indicates center of search
• radius: required, indicates radius of search
• reverse_param: option, (bool indicating the order of the input coordinates)

Example(1)

pg = pa.places(token)

result = pg.load_properties(
    coordinates=[43.0961466, -77.6337776],
    radius=100,
    reverse_param=False
)

convex()

• coordinate_array: required, edges of polygon
• reverse_param: optional, (bool indicating the order of the input coordinates)

Example(2)

pg = pa.places(token)

result = pg.convex(
    coordinates=[[43.0961466, -77.6337776],
     [43.1018722, -77.6334654],
     [43.1010339, -77.6342459]],
    reverse_param=False
)

density()

Radius Load Density:

• unit_input: required, str
  • options: [km, mi, m, ft, yd]
• unit_output: required, str
  • options: [km, mi, m, ft, yd]
• coordinates: optional, list
• reverse_param: optional, (bool indicating the order of the input coordinates)

Example(3)

pg = pa.places(token)
result = pg.density(
    unit_in='ft',
    unit_out='ft',
    coordinate=[43.1010339, -77.6342459],
    radius=100
)

---

Custom Density:

• unit_input: required, str
  • options: [km, mi, m, ft, yd]
• unit_output: required, str
  • options: [km, mi, m, ft, yd]
• custom_option: optional, str
  • city
  • postcode
  • region/state
• custom_utility: optional, int/str,
  • custom_utility specifies the input of custom_option

Example(4)

pg = pa.places(token)
result = pg.density(
    unit_in='ft',
    unit_out='ft',
    custom_option='postcode',
    custom_utility=10980
)

reverse()

• coordinate: required, geographic location of POI
• radius: optional, radius of error
  • Default error radius is 10 ft
• reverse_param: optional, (bool indicating the reversal of the input coordinates)

Example(5)

pg = pa.places(token)
result = pg.reverse(
    coordinate=[43.1017283, -77.6338936],
    radius=10, 
    reverse_param=False
)

batch_reverse()

• coordinates: required, geographic location(s) of POI
• radius: optional, radius of error
  • Default error radius is 10 ft
• reverse_param: optional, (bool indicating the reversal of the input coordinate)

Example(6)

pg = pa.places(token)
result = pg.batch_reverse(
    coordinates=[[43.1017283, -77.6338985],
    [43.0936914, -77.6349024],
    [43.0937299, -77.6350315],
    [43.0930091, -77.6354702],
    [43.09245, -77.6353749]],
    radius=10,
    reverse_param=False
)

forward()

Full Address Geocoding

• full address: optional, user-defined₁ address of the POI

1. Places API's Flex-Formatting AI allows users to define their own U.S address format

Example(7)

pg = pa.places(token)
result = pg.forward(
    full_address="94 Crittenden Way, Brighton, NY, 14623",
)

Parsed Address Geocoding

• street: optional, street on which the POI is located
• number: optional, number of the POI's street
• postcode: optional, zip code or microregion of the POI
• region: optional, state in the USA₁ or region internationally
• city: optional, city where the POI is located
• unit: optional, unit if the POI is non-singular (ex. apartment)

1. If the POI is within USA borders, the region must be the state's 2-letter abbreviation

Example (8.1) without unit

pg = pa.places(token)
result = pg.forward(
    street="Crittenden Way",
    number=94,
    postcode=14623,
    region="NY",
    city="Brighton",
)

Example (8.2) with unit

pg = pa.places(token)
result = pg.forward(
    street="Crittenden Way",
    number=88,
    postcode=14623,
    region="NY",
    city="Brighton",
    unit='Unit 2'
)

batch_forward()

• addresses: optional, list of formatted addresses
• address_file: optional, JSON or XML file of formatted addresses₁

1. Note: Check our documentation for formatting details

Example(9.1) array of addresses

pg = pa.places(token)
result = pg.batch_forward(
    addresses=["88 Crittenden Way, Brighton, NY, 14623, Unit 2",
     "140 Centre Drive, Brighton, NY, 14623",
     "94 Crittenden Way, Brighton, NY, 14623",
     "104 Crittenden Way, Brighton, NY, 14623, Unit 6"
     ]
)

Example(9.2) file of addresses

pg = pa.places(token)
result = pg.batch_forward(
  address_file=address_file.json
)

pg = pa.places(token)
result = pg.batch_forward(
  address_file=address_file.xml
)

→ Download the XML or JSON file as "address_file" to test the examples

---

INSTALLATION

Install the Places API on pip:

$ pip install places_geocoding

OR

Install the Places API on conda:

$ conda install -c Martin Mashalov places_geocoding

---

REQUIREMENTS

• Python3 >= 3.6
• pymongo >= 3.7.0
• numpy
• pandas

---

BUSINESS CONTACT

Our business email contact is: [e-mail]. Please feel free to reach out regarding any product feedback or support.