places-geocode 0.5.8

Python 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

---

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_geocoding 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

To use the Places API for free leave "token" argument blank

Note: Free usage has a rate limit of 2 requests / second

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)
# pg = pa.Places() for free plan

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)
# pg = pa.Places() for free plan

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)
# pg = pa.Places() for free plan

result = pg.density(
    unit_in='ft',
    unit_out='ft',
    coordinates=[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)
# pg = pa.Places() for free plan

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)
# pg = pa.Places() for free plan

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)
# pg = pa.Places() for free plan

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 flex-formatting AI allows for multiple address formats

Example(7)

pg = pa.Places(token)
# pg = pa.Places() for free plan

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)
# pg = pa.Places() for free plan

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

Example (8.2) with unit

pg = pa.Places(token)
# pg = pa.Places() for free plan

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)
# pg = pa.Places() for free plan

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)
# pg = pa.Places() for free plan

result = pg.batch_forward(address_file=address_file.json)

pg = pa.Places(token)
# pg = pa.Places() for free plan

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.