Geocodio's Distance API can calculate the driving and straightline (as the crow flies) distance between U.S. and Canadian addresses or coordinates. Geocodio's Distance API can calculate distances from one origin to multiple destinations, or from many origins to many destinations (a "distance matrix").

Distance calculations are currently available via API only. Spreadsheet upload support is planned for the future. If you're interested in spreadsheet support for distance, please let us know!

Distance modes

Depending on the calculation mode you choose, Geocodio returns:

• Straightline mode: Distance in miles and kilometers (geometric distance between two points)

• Driving mode: Distance in miles and kilometers, plus estimated driving time in seconds

Choosing an endpoint

Geocodio offers three distance endpoints. All of Geocodio's distance endpoints support one-to-one, one-to-many, and many-to-many calculations, as well as driving distance, driving time, and straightline distance.

Use the Distance endpoint when you need instant results for one origin (e.g., showing a customer how far a technician is) when you need to return results to a user in real time. Use Distance Matrix for batch calculations that need to return immediately. Use Distance Jobs when processing large volumes in the background.

Input options

You can provide either addresses or coordinates as input. If you provide addresses, Geocodio geocodes them as part of the distance calculation.

You can also add custom identifiers to your coordinates (e.g., 37.7749,-122.4194,warehouse_sf) to make it easier to match results back to your data.

Enabling Distance API access

To use the Distance API, you must enable Distance permissions for your API key:

1. Go to the API Keys page on your Geocodio dashboard

2. Create a new key or edit an existing one

3. Enable "Distance" and/or "Distance Jobs" permissions

See the Distance API documentation for code examples and detailed endpoint specifications.

Distance API Pricing

Distance calculations use Geocodio's credit system. Distance is a separate product from geocoding, and is not included in geocoding subscriptions (such as Unlimited).

Purchased credits do not expire, and can be used for both geocoding and distance. Volume discounts are available for purchases of 500,000 credits or more. See credit pricing in the Billing section of your account dashboard.

Plan-specific details

Self-Service pay-as-you-go users receive 2,500 free credits per day, which can be used for distance calculations.

Enterprise Flex subscribers can use their subscription's included credits towards distance calculations.

Unlimited Geocoding subscribers (both Self-Service and Enterprise) must pay for distance calculations, but the geocoding component will be done using your dedicated instance(s), so you won't be charged additionally for it.

Distance is not currently available for on-premises license holders.

Credit costs

If you provide coordinates instead of addresses, you do not have to pay for geocoding. Approximate addresses, however, will not be returned. If you need reverse geocoding and distance at the same time, use the geocoding endpoint with distance.

Example pricing scenario

Scenario: 1,000 patients × 50 clinic locations

Straightline distance:

• Geocoding: 1,050 credits (1,000 patients + 50 clinics)

• Distance: 50,000 credits (1,000 × 50 × 1)

• Total: 51,050 credits (Unlimited subscriber: 50,000)

Driving distance:

• Geocoding: 1,050 credits

• Distance: 100,000 credits (1,000 × 50 × 2)

• Total: 101,050 credits (Unlimited subscriber: 100,000)

Distance API Country Support

Geocodio's Distance API supports locations in the United States and Canada. You can calculate distances between:

• U.S. addresses or coordinates

• Canadian addresses or coordinates

• Cross-border routes between the U.S. and Canada

For Canadian addresses, include "Canada" (spelled out, not abbreviated) in the address or use coordinates.