Geo Providers for Geocoding and Distance and Time Calculations

This documentation covers which geo providers one can use with Cosmic Frog, and how they can be used for geocoding and distance and time calculations.

Supported Geocoding Providers

Currently, there are 5 geo providers that can be used for geocoding locations in Cosmic Frog: MapBox, Bing, Google, PTV, and PC*Miler. MapBox is the default provider and comes free of cost with Cosmic Frog. To use any of the other 4 providers, you will need to obtain a license key from the company and add this to Cosmic Frog through your Account. The steps to do so are described in this help article “Using Alternate Geocoding Providers”.

‍

Different geocoding providers may specialize in different geographies; refer to your provider for guidelines.

How to Geocode Locations

Geocoding a location (e.g. a customer, facility or supplier) means finding the latitude and longitude for it. Once a location is geocoded it can be shown on a map in the correct location which helps with visualizing the network itself and building a visual story using model inputs and outputs that are shown on maps.

To geocode a location:

1. You will need to give it some detail on where it is by populating the Address, City, Region (used for States and Provinces), Postal Code, and Country fields in the Customers, Facilities, and Suppliers tables.
   • You do not need to fill out all of these fields for every location. However, the more detailed the location information entered, the more precise the latitude and longitude will be. For example, only populating the Country field will geocode the location to the center of the country, populating Region and Country will geocode the location to the center of the State or Province that was specified in the Region field, etc.
   • For Optimization and Simulation going down to the City or sometimes even Region level is typically sufficient for accurate costing and transport times, also keeping in mind that Address information is often not consistently formatted and therefore the most challenging for a geocoder to match against. For Transportation Optimization applications, going down to the Address level may be necessary.
   • For best results, it is recommended to use the standard 2 letter ISO Country code in the Country field. For example, use US rather than USA, and use GB rather than UK. These standardized country codes can be found in the A-2 column of the table listed on this Wikipedia
2. Click on the Geocode button. Cosmic Frog will now attempt to geocode all records that have blank latitude and longitude fields in the table; locations that already have latitude and longitude specified will not be overwritten.
   • When a subset of records is selected by selecting them in the grid or only a subset of records is shown in the grid due to the application of any filters, the geocoding will still be done for all records in the table that have blank latitude and longitude fields, not just the selected/shown records.
   • If the latitude and longitude fields contain 0’s (rather than being left blank), these will be interpreted as valid coordinates, and the record will not be geocoded.
     

1. When using the default geo provider for Geocoding, MapBox, a message comes up asking the user to choose if they want to return 100% matched results only (when the checkbox is checked) or the best matched result which can be less than a 100% match (when the checkbox is unchecked)
   • Typically, not all locations will be geocoded when requiring 100% matches only. Therefore, a 2-step strategy where first only 100% matches are geocoded, marking the locations that were not geocoded in this step by for example putting a note in the Notes field or a custom field, then doing a second geocoding pass through where 100% matches are not required and checking these latter locations visually on a map (filtering them out using the Notes of custom field) can help achieve the most accurate geocoding results.
2. Best practice is to check the geocoding results on a map as missed assignments are possible and often easiest to identify visually.

Transport Distances and Transport Times

For costs and capacities to be calculated correctly, it may be needed to add transport distances and transport times to Cosmic Frog models. There are defaults that will be used if nothing is entered into the model, or users can populate these fields, either themselves or by using a Distance Lookup Utility. Here the tables where distances and times can be entered, what happens if nothing has been entered, and how users can utilize the Distance Lookup Utility will be explained.

‍

There are multiple Cosmic Frog input tables that have input fields related to Transport Distance, and Transport Time, including Speed which can also be used to calculate transport time from a Transport Distance (time = distance / speed). These all have their own accompanying UOM (unit of measure) field. Here is an overview of the tables which contain Distance, Time and/or Speed fields:

For Optimization (Neo), this is the order of precedence that is applied when multiple tables and fields are used:

1. If the Transport Distance and/or Transport Time fields on the Transportation Policies table are populated, these values will be used for distance and time.
2. If the Transport Distance and/or Transport Time fields on the Transportation Policies table are not populated, but those on the Transit Matrix table are, then the values from the Transit Matrix table are used.
3. If the Transport Distance and Transport Time fields on both the Transportation Policies and Transit Matrix tables are not populated, Cosmic Frog will calculate these during an Optimization (Neo) run using the latitude & longitude pairs of origin and destination. For Distance, a straight-line calculation + Circuity Factor is used, and Time is calculated as Distance / Average Speed. The Circuity Factor and Average Speed are specified in the Model Settings table, defaults are 17% and 55 MPH respectively:

For Transportation (Hopper) models, this is the order of precedence when multiple tables and fields are being used:

1. If the Transport Distance and/or Transport Time fields on the Transit Matrix table are populated, these values will be used for distance and time.
2. If the Transport Distance and Transport Time fields on the Transit Matrix table are not populated, Cosmic Frog will calculate these during a Transportation (Hopper) run using the latitude & longitude pairs of origin and destination. As described under bullet 3 above for Neo, it will use the Circuity Factor from the Model Settings table to calculate the distance. If the Speed field on the Transportation Assets table is used, then this value is used to calculate the Transport Time from the Transport Distance. If no asset speed is specified, then the Average Speed from the Model Settings table is used to calculate Transport Time from Transport Distance.

To populate these input tables and their pertinent fields, user has following options:

1. Populate individual table records "manually" (e.g. from source data imports).
2. For table records that use Groups or Named Filters as inputs for for example Origin and/or Destination Name, the Lookups table can be used to lookup distances, times, speeds for individual origin-destination pairs from underlying source data that is expanded out into the individual location combinations.
3. The Transit Matrix table can be populated using the Distance Lookup Utility, which will be covered next.

Using the Distance Lookup Utility to Populate the Transit Matrix

Cosmic Frog users can find multiple handy utilities in the Utilities section of Cosmic Frog - here we will cover the Distance Lookup utility. This utility looks up transportation distances and times for origin-destination pairs and populates the Transit Matrix table. As Geo Providers, Bing, PC Miler and Azure can be used if the user has a license key for these. In addition, there is a new free PC Miler-UltraFast option which can look up accurate road distances within Europe and North America without needing a license key. This is also a very fast way to lookup distances. Lastly, the Great Circle Geo Provider option calculates the straight-line distance for origin-destination pairs based on latitudes & longitudes. We will look at the configuration options of the utility using the next 2 screenshots:

1. Click on the icon with 3 horizontal bars to open Cosmic Frog's Module Menu and select Utilities from the list.
2. In the Transportation section, click on Distance Lookup to open the Distance Lookup Utility. Configure it as follows in the center part of the screen:
3. Choose the Resource Size you want to use to run the Utility. For just a few distance lookups, the default of Mini will suffice, but users may want to select a larger resource to speed up the process in case of thousands of lookups to be performed.
4. A Timeout can be set after which time the utility will stop the lookups if any were still running. This is set in minutes, and the default is 60.
5. Choose the unit of measure (UOM) to be used for the distances that will be calculated, either miles (MI) or kilometers (KM).
6. Choose the Geo Provider to perform the distance calculations. PCMiler-UltraFast is the default and can be used free of charge. The other free option is Great Circle, which calculates the straight-line distance between an origin and destination based on the latitude & longitude of the origin and destination. The other options are PC Miler, Bing, and Azure, which can be used if user has a license (API) Key for these (to be entered into Geo Provider API Key parameter further below).
7. The Arc Defining Table refers to the input table of which the records should be used to determine for which origin-destination or origin-destination-asset combinations Distances will be calculated. Options are Transportation Policies (used for Optimization and Simulation) and Shipments (used for Simulation and Transportation).
   
   1. Note that when the Shipments table is selected as the Arc Defining Table, customer-customer lanes will only be distanced if they both have shipments coming from the same facility.

1. If the current Transit Matrix is populated already, choose if it should be overwritten (the default) or not. If not overwriting the Transit Matrix table, new records will be appended to the existing table.
   
   1. Note that when not overwriting the Transit Matrix table, the Geo Provider will only be called on records that are not already in the Transit Matrix table. So when for example just adding a few facilities or customers to the model, it will add the new relevant records to the Transit Matrix table, but it will not rerun all the lookups.
2. If the Shipments table is used as the Arc Defining Table (see bullet 7 for the previous screenshot above), then user has the option to consider all distances symmetric (the default) or not. Considering them symmetric means that the distance from a location A to a location B is considered to be the same as the distance from location B to location A, in which case fewer lookups have to be done.
3. If the Shipments table is used as the Arc Defining Table (see bullet 7 for the previous screenshot above), then user can specify the maximum number of closest neighbors here. In the case of many locations to consider in a transportation optimization (Hopper) problem, generating an all-to-all matrix of all possible origin and destination combinations can result in millions of lookups. Considering that in most cases, only locations that are close to each other will be considered as potential legs of a route, it can make sense to limit the amount of exact distance calculations to an upper limit of closest locations. The default is set to 10.
4. If using Azure, Bing or PC Miler as the Geo Provider (see bullet 6 for the previous screenshot above), then the user's Geo Provider API Key needs to be entered here.
5. Avoid Ferries (Azure, Bing, and PC Miler only) - when turned on (toggle to the right, blue) this will generate distances and times for routes that avoid using ferries.
6. Avoid Border Crossings (Azure, Bing, and PC Miler only) - when turned on (toggle to the right, blue) this will generate distances and times for routes that avoid crossing borders.
7. Handling Tolls (Azure, Bing, and PC Miler only) - user has 3 options to choose from with regards to how tolls should be handled:
   
   1. Default: tolls are allowed, the shortest distance route will be calculated.
   2. Avoid: tolls are not allowed, the shortest distance route without tolls will be calculated.
   3. Minimize: tries to avoid tolls on the calculated route.
8. How many lookups will be done in a single batch (i.e. these lookups within a batch are submitted at the same time and results are returned for all of them together once all the lookups are done) is set by the Batch Size. The default is 100 and it is generally not recommended to change this setting, unless running into issues. Many Geo Providers have a maximum number of requests per minute, which can be exceeded if too many records are sent at once. If running into problems with too many requests sent, decrease this number.
9. The Max Lookup Limit sets the total amount of lookups the utility will perform for one run. The default is set to 20,000 and this is to avoid surprises! Lookups to 3^rd party providers can be costly and it may be challenging to know for sure how many lookups will be needed for a model. So this is a guardrail to prevent running many more lookups than anticipated. If it is detected that the limit will be exceeded, no lookups will be done and a message stating how many lookups are needed will come up.
10. If changes have been made to the Parameters above, they can be reset to their defaults by clicking on the Reset button.
11. If the Parameters have been configured as desired, user can click on the Run Utility button to start the distance calculations. Once done, the results can be found in the Transit Matrix table.

Note that when using the Great Circle geo provider for Distance calculations, only the Transport Distance field in the Transit Matrix table will be populated. The Transport Time will be calculated at run time using the Average Speed on the Model Settings table.

‍

To finish up, we will walk through an example of using the Distance Lookup utility on a simple model with 3 customers (CZs) and 2 distribution centers (DCs), which are shown in the following 2 screenshots of the Customers and Facilities tables:

We can use Groups and/or Named Table Filters in the Transportation Policies table if we want to make 1 policy that represents all possible lanes from the DCs to the customers:

Next, we run the Distance Lookup utility with following settings:

• Distance UOM = KM
• Geo Provider = PCMiler
• Arc Defining Table = Transportation Policies

This results in the following 6 records being added to the Transit Matrix table - 1 for each possible DC-CZ origin-destination pair:

‍