Managing Locations¶

Locations are the cities, towns, and addresses where freight is picked up and delivered. The system uses locations across shipments, legs, stops, truck assignments, and driver home bases to provide consistent address data, timezone support, and mileage calculations.

Overview¶

A location record represents a single geographic point -- typically a city and state/province within the United States or Canada. When you type a location into any location field in the system, the TMS searches existing records first and then queries Google Maps to find new matches. Validated locations include GPS coordinates, a timezone, and a formatted address, which are used for ETA calculations, check calls, and dispatch communications.

Getting There¶

Locations are accessed primarily through location dropdown fields on other records (trucks, drivers, stops, check calls). The dedicated Locations list is available to admins who need to review, clean up, or manually create location records.

How It Works¶

Display Name Format¶

Every location's display name is built from its address components in this format:

City, ST CC ZIP

For example: "Boise City, OK US 73933" or "Toronto, ON CA M5V". If the ZIP code is a placeholder ("00000"), it is omitted from the display name.

Creating a Location¶

Locations are typically created automatically when you type into a location field on a truck, driver, stop, or check call record. The system searches existing locations first, and if no match is found, it queries the Google Places API to suggest results. Selecting a suggestion creates the location record automatically.

To create a location manually:

Open the Locations list and click New.
Fill in the required address fields:
Street Address -- The street-level address (or the city name if no specific street applies)
City -- The city or town name
State/Province -- The state or province code (e.g., "TX", "ON")
ZIP/Postal Code -- The US ZIP code or Canadian postal code
Country -- United States or Canada
Click Save.

Note: Each combination of city, state, country, and ZIP code must be unique. If a location with the same values already exists, you will see a validation error.

Normalization¶

When you create or edit a location, the system automatically normalizes the address components:

City is title-cased (e.g., "new york" becomes "New York")
State/Province is upper-cased (e.g., "tx" becomes "TX")
ZIP/Postal Code is upper-cased (for Canadian postal codes like "m5v 3a8" to "M5V 3A8")

This normalization keeps location data consistent and prevents duplicate records that differ only in casing.

Google Maps Validation¶

When a location is created from a Google Places search, the system automatically fetches additional data from the Google Maps API:

Formatted Address -- The standardized address returned by Google (shown on BOLs and dispatch communications)
Latitude and Longitude -- GPS coordinates used for distance calculations and ETA estimation
Timezone -- The IANA timezone (e.g., "US/Eastern", "Canada/Pacific") derived from the coordinates, used to display local times for stops, check calls, and ETAs
Google Place ID -- A unique identifier for the location in Google's database

Locations that have been validated through Google Maps are marked with a green row color in the list view. Locations without Google validation appear in yellow.

The Google Maps Data tab on the location form shows all validation details, including the formatted address, coordinates, timezone, and any validation errors.

Tip: Google Maps validation requires a Google Maps API key. If locations are not being auto-validated, check with your admin that the API key is configured in the system settings.

Editing a Location¶

Open a location from the list and update the address fields as needed. The Status section on the right side of the form shows:

Google Validated -- Whether the location has been validated through Google Maps
Last Validated -- When the last Google Maps validation occurred
Active -- Whether the location is active in the system

The Notes tab provides a free-text area for any additional information about the location (gate codes, delivery instructions, hours of operation, etc.).

Archiving Locations¶

To remove a location from active use without deleting it, uncheck the Active checkbox on the location form. Archived locations are hidden from dropdown searches by default but can be found using the Inactive filter on the list.

Searching and Filtering¶

The location list includes a search bar and filter panel.

Search fields: Type in the search bar to search across street, city, state, ZIP, and formatted address.

Quick filters:

Filter	What It Shows
United States	Locations with country set to US
Canada	Locations with country set to Canada
Google Validated	Locations that have been validated through Google Maps
Not Validated	Locations without Google validation
Has Validation Error	Locations where Google validation encountered an error
Has Coordinates	Locations with latitude and longitude values
Missing Coordinates	Locations without GPS coordinates
Eastern Time / Central Time / Mountain Time / Pacific Time	Locations in the selected timezone
Recently Validated (Last 30 days)	Locations validated by Google in the past 30 days
Active / Inactive	Filter by active or archived status

Group by: You can group the location list by Country, State/Province, Timezone, Validation Status, or Active Status.

Tips & Common Questions¶

Q: I typed a city name but no suggestions appeared. What happened? The Google Places autocomplete requires at least 3 characters and a configured API key. If no results appear, the API key may not be set up, or the location may not match any known US or Canadian address. You can always create the location manually.

Q: A location shows as "Not Validated" -- does that matter? Unvalidated locations work fine for basic dispatching and record-keeping. However, they will not have GPS coordinates or a timezone, which means the system cannot calculate distances or show local times for that location. If accuracy matters, try editing the address fields to trigger a new Google validation.

Q: I see a duplicate error when creating a location. How do I find the existing one? The system enforces a unique constraint on the combination of city, state, country, and ZIP. Search for the city name in the location list to find the existing record. Remember that casing does not matter -- "Dallas" and "dallas" are treated as the same city after normalization.

Q: Why does the ZIP show as "00000" on some locations? Placeholder ZIPs are used when a location was imported or migrated without a known postal code. You can edit the location to add the correct ZIP. Placeholder ZIPs are hidden from the display name.

Carrier Setup -- Carriers use locations for truck and driver home bases
Equipment -- Trucks have base location and current location fields
Driver Management -- Drivers have home and current location fields