geocentroid 0.0.10

A package to calculate the centroid of a list of addresses.

Introduction

A python package that can be used to generate a centroid from a given list of addresses/geocoded locations. Further, weights can be attached to each location, to give it a bias, and calculate a weighted centroid.

Requirements

• Python 3.5 or later
• Google Maps API Key

Installation

pip install geocentroid

Usage

This example shows how to use the geocentroid package.

import geocentroid 

geo_calculator = geocentroid.CentroidCalculator(api_key = "ADD YOUR GOOGLE API KEY HERE")

# Geocoding an address.
waterloo_address = geo_calculator.geocode_address("200 University Ave W, Waterloo, ON N2L 3G1")

# Calculate the centroid given two geocoded locations with weights.
centroid_of_two_addresses = geo_calculator.calculate_two_point_centroid(43.4740533, -80.5205138, 1, 43.4683522, -80.5425357, 1)

# Calculate the centroid for a list of addresses:
centroid_of_addresses = geo_calculator.get_centroid(["200 University Ave W, Waterloo, ON N2L 3G1",
                                                     "CIF Waterloo Ontario",
                                                     "King Street towers, waterloo ontario"])

# Calculate the centroid for a list of geocoded addresses:
centroid_of_addresses = geo_calculator.get_centroid([43.4740533, -80.5205138],
                                                    [43.4683522, -80.5425357],
                                                    [44.4482542, -79.4425354]])

# Calculate the centroid for a list of addresses with weights
centroid_of_addresses = geo_calculator.get_centroid([[43.4740533, -80.5205138, 10],
                                                     [43.4683522, -80.5425357, 22],
                                                     ["King Street towers, waterloo ontario", 38]])

For test cases check out: tests.

Documentation

1) geocode_address(self, address)

Geocodes an address to get the latitude and longitude coordinates.

Parameters:

• address (str): The address to geocode.

Returns:

• [lat, lng] (list): The latitude and longitude coordinates of the address.

2) calculate_two_point_centroid(self, lat1, lng1, w1, lat2, lng2, w2)

Calculates the centroid of two points with weights.

Parameters:

• lat1 (float): The latitude of the first point.
• lng1 (float): The longitude of the first point.
• w1 (int): The weight of the first point.
• lat2 (float): The latitude of the second point.
• lng2 (float): The longitude of the second point.
• w2 (int): The weight of the second point.

Returns:

• [clat, clng, w1 + w2] (list): The latitude, longitude, and combined weight of the centroid.

3) generate_centroid(self, geocoded)

Generates the centroid of a list of geocoded addresses with weights.

Parameters:

• geocoded (list): A list of geocoded addresses.

Returns:

• [clat, clng, w] (list): The latitude, longitude, and combined weight of the centroid.

4) get_centroid(self, addresses)

Calculates the centroid of a list of addresses.

Parameters:

• addresses (list): A list of addresses. Each element in the addresses list can be:
  • A string representing the address,
  • A geocoded address [lat, lng],
  • An address with a weight [address, weight] | [lat, lng, weight].

Returns:

• [clat, clng, w] (list): The latitude, longitude, and combined weight of the centroid.

Testing

To run the tests, clone the repository and from the root directory run:

python3 -m unittest path/to/your/test/test_centroid_calculator.py

Building the Package and Installing Locally

Clone the repository then build the packages using:

pip3 install wheel
python3 setup.py bdist_wheel sdist
pip3 install .