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.
     
3. 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.
4. 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:

Input Table	Distance Field	Time Field	Speed Field	Used By
Transportation Policies	Transport Distance	Transport Time		Optimization (Neo), Simulation (Throg)
Transportation Assets			Speed	Simulation (Throg), Transportation (Hopper)
Transit Matrix	Transport Distance	Transport Time		Optimization (Neo), Transportation (Hopper)
Model Settings			Average Speed	Optimization (Neo), Transportation (Hopper)

 

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 which can use either PC Miler or Great Circle as geo providers to populate the Transit Matrix input table:

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. Choose the unit of measure (UOM) to be used for the distances that will be calculated, either miles (MI) or kilometers (KM).
5. Choose the Geo Provider to perform the distance calculations. Great Circle is the default and can be used free of charge. It calculates the straight-line distance between a source and destination based on the latitude & longitude of the source and destination. The other option is PC Miler, which can be used if user has a PC Miler API Key (to be entered into the Utility parameters further below).
6. Choose the input table of which the records should be used to determine for which source-destination or source-destination-asset combinations Distances will be calculated. Options are Transportation Policies (used for Optimization and Simulation) and Shipments (used for Simulation and Transportation).
7. 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.
8. If the Shipments table is used as the Arc Defining Table (see bullet 6 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.
9. If the Shipments table is used as the Arc Defining Table (see bullet 6 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 thousands 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.
10. If using PC Miler as the Geo Provider (as chosen under bullet 5 above), then the user’s PC Miler API Key needs to be entered here.
11. If changes have been made to the Parameters above, they can be reset to their defaults by clicking on the Reset button.
12. 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, let’s 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: