Compute a driving route between two addresses
curl --request POST \
--url https://api.example.com/v1/routes \
--header 'Content-Type: application/json' \
--header 'X-API-Key: <api-key>' \
--data '
{
"origin": "<string>",
"destination": "<string>"
}
'import requests
url = "https://api.example.com/v1/routes"
payload = {
"origin": "<string>",
"destination": "<string>"
}
headers = {
"X-API-Key": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'X-API-Key': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({origin: '<string>', destination: '<string>'})
};
fetch('https://api.example.com/v1/routes', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.example.com/v1/routes",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'origin' => '<string>',
'destination' => '<string>'
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"X-API-Key: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.example.com/v1/routes"
payload := strings.NewReader("{\n \"origin\": \"<string>\",\n \"destination\": \"<string>\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("X-API-Key", "<api-key>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.example.com/v1/routes")
.header("X-API-Key", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"origin\": \"<string>\",\n \"destination\": \"<string>\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.example.com/v1/routes")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["X-API-Key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"origin\": \"<string>\",\n \"destination\": \"<string>\"\n}"
response = http.request(request)
puts response.read_body{
"route": {
"total_distance_miles": 2015.3,
"total_duration_minutes": 1834.2,
"start": {
"lat": 34.0522,
"lng": -118.2437
},
"end": {
"lat": 41.8781,
"lng": -87.6298
},
"polyline": "encoded_polyline_string..."
},
"request_id": "req_abc123def456"
}{
"detail": [
{
"loc": [
"<string>"
],
"msg": "<string>",
"type": "<string>",
"input": "<unknown>",
"ctx": {}
}
]
}API Reference
POST /v1/routes
Returns the route’s geometry, total distance, and total duration in our flat Route shape. Use this when you don’t have your own routing infrastructure. If you do, construct Route objects directly and pass them to downstream endpoints — this endpoint exists for convenience, not as a required first step.
POST
/
v1
/
routes
Compute a driving route between two addresses
curl --request POST \
--url https://api.example.com/v1/routes \
--header 'Content-Type: application/json' \
--header 'X-API-Key: <api-key>' \
--data '
{
"origin": "<string>",
"destination": "<string>"
}
'import requests
url = "https://api.example.com/v1/routes"
payload = {
"origin": "<string>",
"destination": "<string>"
}
headers = {
"X-API-Key": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'X-API-Key': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({origin: '<string>', destination: '<string>'})
};
fetch('https://api.example.com/v1/routes', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.example.com/v1/routes",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'origin' => '<string>',
'destination' => '<string>'
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"X-API-Key: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.example.com/v1/routes"
payload := strings.NewReader("{\n \"origin\": \"<string>\",\n \"destination\": \"<string>\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("X-API-Key", "<api-key>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.example.com/v1/routes")
.header("X-API-Key", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"origin\": \"<string>\",\n \"destination\": \"<string>\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.example.com/v1/routes")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["X-API-Key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"origin\": \"<string>\",\n \"destination\": \"<string>\"\n}"
response = http.request(request)
puts response.read_body{
"route": {
"total_distance_miles": 2015.3,
"total_duration_minutes": 1834.2,
"start": {
"lat": 34.0522,
"lng": -118.2437
},
"end": {
"lat": 41.8781,
"lng": -87.6298
},
"polyline": "encoded_polyline_string..."
},
"request_id": "req_abc123def456"
}{
"detail": [
{
"loc": [
"<string>"
],
"msg": "<string>",
"type": "<string>",
"input": "<unknown>",
"ctx": {}
}
]
}The
/v1/routes endpoint computes a driving route between two points. It returns route geometry, total distance, and estimated duration.
When to Use
Use this endpoint when you don’t have your own routing infrastructure. Partners with existing routing layers should skip this endpoint and pass their ownRoute object directly to /v1/stations/enrich-distances and /v1/optimize.
Notes
- Addresses can be specified as natural language strings (e.g., “Los Angeles, CA”) or as “lat,lng” coordinate pairs
- Routes are computed using driving directions optimized for typical road conditions
- The returned
polylinefield uses the standard Google Polyline Algorithm Format - Maximum route length depends on routing provider — extremely long routes may return an error
Authorizations
Body
application/json