Geocodio's Distance API supports distance matrix calculations for both driving and straightline distance. A distance matrix calculates the distance between every combination of origins and destinations in a single request.

How it works

If you have 3 origins and 10 destinations, Geocodio will return a distance matrix with 30 results (3 × 10), i.e., the distance from each origin to each destination.

This is useful for:

• Determining which warehouse should ship to each customer

• Assigning service technicians to job sites

• Balancing sales territories by travel time

• Site selection analysis

What if each origin already has a matching destination?

Sometimes the pairing is already decided. Each customer has an assigned sales rep, and you want to know how far each customer is from their own rep. A full matrix would measure every customer against every rep, and you would pay for results you never use.

For this, set calculation_type=pairs and send origins and destinations as two lists of the same length. Geocodio measures the first origin against the first destination, the second against the second, and so on. With 1,000 customers and 1,000 reps:

• As a matrix: 1,000,000 calculations (1,000 × 1,000)

• As pairs: 1,000 calculations, one per customer

The response has the same shape as a matrix. Each row holds exactly one destination, and the rows come back in the order you sent the pairs. Pairs that Geocodio cannot resolve or route are not billed. The filtering parameters are not available for pairs, since every pair in the request is one you asked for.

Pairs work with the Distance Matrix and Distance Jobs endpoints. If you leave out calculation_type, Geocodio calculates a full matrix as before.

Endpoints

Geocodio has two endpoints for matrix calculations:

Distance Matrix (synchronous)

• Up to 10,000 calculations per request, or up to 2,500 one-to-one pairs

• Returns results immediately

• Best for batch processing that needs quick turnaround

Distance Jobs (asynchronous)

• Up to 50,000 calculations per job, or up to 50,000 one-to-one pairs

• Processes in the background

• Notifies you via webhook when complete

• Best for large-scale calculations

Example

To find which of 5 warehouses is closest to each of 100 customers:

• Origins: 5 warehouse addresses or coordinates

• Mode: Driving distance

• Destinations: 100 customer addresses or coordinates

• Total calculations: 500 (5 × 100)

The API will return the driving distance and driving time from each warehouse to each customer.

See the Distance Matrix API documentation for request/response formats and code examples.