# Matrices

The Matrix API calculates distances and times between multiple start and destination locations.
It can compute full NxN matrices or asymmetric matrices with separate origin and destination sets.


## Compute a matrix

 - [POST /matrix](https://docs.graphhopper.com/openapi/matrices/postmatrix.md): Calculate a matrix of travel times and/or distances between N origins and M destinations.

This includes the common cases of routes from one origin to many destinations, or from many origins to one
destination.

## Compute a matrix

 - [GET /matrix](https://docs.graphhopper.com/openapi/matrices/getmatrix.md): For N origins and M destinations, compute routes from all origins to all destinations and output
the result as a matrix of travel times and/or distances.

This includes the common cases of routes from one origin to many destinations, or from many origins to one
destination.

## Submit a matrix computation job

 - [POST /matrix/calculate](https://docs.graphhopper.com/openapi/matrices/calculatematrix.md): An alternate endpoint for computing a large matrix asynchronously, where a request against the regular 
endpoint would result in a timeout.

The request format is the same, but instead of the result, you are given a job identification number that
you can use to retrieve the result once it is available.
        
In most cases, prefer the regular endpoints.

Here are some full examples via curl:
bash
$ curl -X POST -H "Content-Type: application/json" "https://graphhopper.com/api/1/matrix/calculate?key=[YOUR_KEY]" -d '{"points":[[13.29895,52.48696],[13.370876,52.489575],[13.439026,52.511206]]}'
{"job_id":"7ac65787-fb99-4e02-a832-2c3010c70097"}


Pick the returned job_id and use it in the next GET requests:
bash
$ curl -X GET "https://graphhopper.com/api/1/matrix/solution/7ac65787-fb99-4e02-a832-2c3010c70097?key=[YOUR_KEY]"
{"status":"waiting"}


When the calculation is finished (status:finished) the JSON response will contain the full matrix JSON under solution:
bash
$ curl -X GET "https://graphhopper.com/api/1/matrix/solution/7ac65787-fb99-4e02-a832-2c3010c70097?key=[YOUR_KEY]"
{"solution":{"weights":[[0.0,470.453,945.414],[503.793,0.0,580.871],[970.49,569.511,0.0]],"info":{"copyrights":["GraphHopper","OpenStreetMap contributors"]}},"status":"finished"}


Please note that if an error occured while calculation the JSON will not have a status but contain directly the error message e.g.:
json
{"message":"Cannot find from_points: 1"}

And the optional hints array.

## Retrieve result of a matrix computation job

 - [GET /matrix/solution/{jobId}](https://docs.graphhopper.com/openapi/matrices/getmatrixsolution.md)