canterburycommuto 0.1.11

CanterburryCommunto

CanterburyCommuto

The aim of CanterburyCommuto is to find commuting information including time and distance travelled before, during, and after the overlap, if it exists, between two routes.

It relies on the Google Maps API.

How to use it

Install the package

To use CanterburyCommuto, you need to clone the respository first. You can do this by running the following command in your terminal:

git clone https://github.com/PeirongShi/CanterburyCommuto.git

And then install the requirements

cd CanterburyCommuto
pip install -r requirements.txt

Get Google API Key

To use CanterburyCommuto, it is necessary to have your API key ready from Google.

0. You need a Google Account.
1. Go to Google Cloud Console.
2. Create a billing account. If the usage of API is below a certain threshold, no payment will be needed.
3. Click on the button next to the Google Cloud logo to make a new project.
4. From Quick access, find APIs&Services. Click on it.
5. Go to the API Library.
6. Type in Google Maps in the search bar.
7. Enable the Google Maps Directions API. (It is probably harmless to enable more APIs than needed.) You will be able to create an API key in this step.
8. Go to Credentials, where you will find your key stored.

Caveat: Do not share your Google API key to the public. Your key is related to your billing account. If abused, high costs will be incurred.

For Google Maps Routes APIs, the essential services—Directions and Distance Matrix APIs—each include a free monthly usage cap of 10,000 requests. Beyond that, usage from 10,001 to 100,000 requests is billed at $5 per 1,000 requests, and any usage exceeding 100,000 requests is billed at a reduced rate of $4 per 1,000 requests. The advanced versions—Directions Advanced and Distance Matrix Advanced—offer enhanced features such as traffic-aware routing and waypoint optimization. These have a lower free monthly cap of 5,000 requests, with usage from 5,001 to 100,000 requests charged at $10 per 1,000 requests, and any requests above 100,000 billed at $8 per 1,000 requests.

This Python package uses the essential tier of the Google Maps Directions API, relying only on basic parameters and avoiding advanced features, thereby qualifying for standard usage rates.

Launch the computation

You can generate a test dataset with the script

python CanterburyCommuto/canterburycommuto/Sample.py

Otherwise, you need to create a csv file with the following columns:

0. ID - Each observation's ID (optional).
1. OriginA_latitude – The latitude of the starting location of Route A.
2. OriginA_longitude – The longitude of the starting location of Route A.
3. DestinationA_latitude – The latitude of the ending location of Route A.
4. DestinationA_longitude – The longitude of the ending location of Route A.
5. OriginB_latitude – The latitude of the starting location of Route B.
6. OriginB_longitude – The longitude of the starting location of Route B.
7. DestinationB_latitude – The latitude of the ending location of Route B.
8. DestinationB_longitude – The longitude of the ending location of Route B.

Next, import the main function.

from canterburycommuto.CanterburyCommuto import Overlap_Function

Before running the main function to retrieve commuting data, it's recommended to first run the estimation command. This provides an estimate of the number of Google API requests and the potential cost, assuming the free tier is exceeded. This helps users make informed decisions, as extensive API use can become costly depending on route complexity and Google's pricing.

python -m canterburycommuto estimate \
    --csv_file origin_destination_coordinates.csv \
    --approximation "exact" \
    --commuting_info "no" \
    --home_a_lat "home_A" \
    --home_a_lon "home_A_lon" \
    --work_a_lat "work_A" \
    --work_a_lon "work_A_lon" \
    --home_b_lat "home_B" \
    --home_b_lon "home_B_lon" \
    --work_b_lat "work_B" \
    --work_b_lon "work_B_lon" \
    --id_column "ID" \
    --output_file "exact_only_output.csv" \
    --skip_invalid True

Then, to use CanterburyCommuto, you can run the command in a way like the example illustrated below. This example chooses to create 150-meter buffers along the two routes to find the buffers' intersection ratios for each route. The output is "buffer_output.csv". The --skip_invalid True option tells the program to skip over rows with missing or invalid data, allowing the analysis to continue uninterrupted. The --save_api_info True option enables saving API responses to a file for future reference or debugging purposes.

!python -m canterburycommuto overlap \
    --csv_file origin_destination_coordinates.csv \
    --api_key "API_KEY" \
    --buffer 150 \
    --approximation "yes with buffer" \
    --home_a_lat "home_A" \
    --home_a_lon "home_A_lon" \
    --work_a_lat "work_A" \
    --work_a_lon "work_A_lon" \
    --home_b_lat "home_B" \
    --home_b_lon "home_B_lon" \
    --work_b_lat "work_B" \
    --work_b_lon "work_B_lon" \
    --id_column "ID" \
    --output_file "buffer_percentage_output.csv" \
    --skip_invalid True \
    --save_api_info True \
    --yes

You can run this package on as many route pairs as you wish, as long as these route pairs are stored in a csv file in a way similar to the output of Sample.py in the repository. Don't worry if the order of the columns in your csv file is different from that of the Sample.py output, as you can manually fill in the column names corresponding to the origins and destinations of the route pairs in CanterburyCommuto.

For simplified execution using a configuration file and additional usage details, please refer to the example.ipynb file located in the example folder.

Results

The output will be a csv file including the GPS coordinates of the route pairs' origins and destinations and the values describing the overlaps of route pairs. Graphs are also produced to visualize the commuting paths on the OpenStreetMap background. By placing the mouse onto the markers, one is able to see the origins and destinations of route A and B marked as Origin A and Destination A in red and Origin B and Destination B in green. Distances are measured in kilometers and the time unit is minute. Users are able to calculate percentages of overlaps, for instance, with the values of the following variables. As shown below, the list explaining the meaning of the possible output variables:

0. ID - Each observation's ID (optional).

1. OriginA_latitude – The latitude of the starting location of Route A.

2. OriginA_longitude – The longitude of the starting location of Route A.

3. DestinationA_latitude – The latitude of the ending location of Route A.

4. DestinationA_longitude – The longitude of the ending location of Route A.

5. OriginB_latitude – The latitude of the starting location of Route B.

6. OriginB_longitude – The longitude of the starting location of Route B.

7. DestinationB_latitude – The latitude of the ending location of Route B.

8. DestinationB_longitude – The longitude of the ending location of Route B.

9. aDist: Total distance of route A.

10. aTime: Total time to traverse route A.

11. bDist: Total distance of route B.

12. bTime: Total time to traverse route B.

13. overlapDist: Distance of the overlapping segment between route A and route B.

14. overlapTime: Time to traverse the overlapping segment between route A and route B.

15. aBeforeDist: Distance covered on route A before the overlap begins.

16. aBeforeTime: Time spent on route A before the overlap begins.

17. bBeforeDist: Distance covered on route B before the overlap begins.

18. bBeforeTime: Time spent on route B before the overlap begins.

19. aAfterDist: Distance covered on route A after the overlap ends.

20. aAfterTime: Time spent on route A after the overlap ends.

21. bAfterDist: Distance covered on route B after the overlap ends.

22. bAfterTime: Time spent on route B after the overlap ends.

23. aIntersecRatio: The proportion of the buffer area of Route A that intersects with the buffer of Route B. It is calculated as:

    aIntersecRatio = Intersection Area / Area of A

24. bIntersecRatio: The proportion of the buffer area of Route B that intersects with the buffer of Route A.

25. aoverlapDist: Distance of the overlapping segment on route A inside the buffer intersection with route B.

26. aoverlapTime: Time to traverse the overlapping segment on route A.

27. boverlapDist: Distance of the overlapping segment on route B inside the buffer intersection with route A.

28. boverlapTime: Time to traverse the overlapping segment on route B.

Overlap Function Options

This table summarizes the available options for the package's main function, including whether commuting information before and after the overlap can be considered, how realistic the results are, and a brief description. "Commuting Information (Pre/Post Overlap) Available?" refers to whether the system can provide separate commuting data for the parts of the route before and after the overlapping segment of a shared commute.

Option Name	Commuting Information (Pre/Post Overlap) Available?	Closeness to Reality (0 = Not Close, 10 = Very Close)	Description
Common Node	Yes	6	This option finds the first and last common nodes along the two routes' polylines given by Google Maps. The overlapping information is obtained via these nodes.
Rectangle Approximation	Yes	5 to 7	As a modified variant of the Common Node Method, this option draws rectangles along the route segments before and after the first and last common nodes of the two routes. It may extend the overlapping range of the route pair if the overlapping area ratio of these rectangles exceeds certain thresholds, which is set to 50% by default, but adjustable by the users.
Buffer Area Ratio	No	8	This option creates 100-meter (m) buffers along the two routes to find the ratios of the buffers' intersection area for each route separately. The buffer width is 100m by default, but it may be adjusted upon the users' wishes.
Buffer Route Node	Yes	6 to 8	This option considers the routes and buffers as lines and geometric shapes. It finds the closest nodes to the points of intersections among the buffer polygons and route lines. The overlapping information is determined based on these closest nodes.
Buffer Route Intersection	Yes	9	As an improved version of the Buffer Route Node method, this option directly records the GPS coordinates corresponding to the points of intersections among the buffer polygons and the route lines and then proceeds to compute the overlapping distance and time information based on these GPS coordinates.

Acknowledgment

This Python package CanterburyCommuto is created under the instruction of Professor Florian Grosset and Professor Émilien Schultz.

The Specification on API Usage section, located in doc, was written with assistance from OpenAI's ChatGPT, as its explanation on the details of API utilization is relatively clear.

If you have any question, please open an issue.