API ReferenceRoute
Retrieve a route
Returns a route with its ordered stops, assigned vehicle, total distance, total duration and ETAs.
Returns a route with its ordered stops, assigned vehicle, total distance, total duration and ETAs.
Use this endpoint to inspect a single route without pulling the full plan — for example to render a driver dashboard, build a public route page, or sync an individual route into your TMS.
Authorization
api_key private_key<token>
The Routal API authenticates requests with an API key passed as the private_key query string parameter. Generate and rotate your keys from the Developer Settings section of your Routal workspace.Never ship API keys to a browser or mobile app — they must stay server-side.
In: query
Path Parameters
id*string
Route ID
Match
^[0-9a-f]{24}Response Body
application/json
application/json
application/json
application/json
curl -X GET "https://example.com/v2/route/string"{
"id": "4f75d991ac359f8c4c79d762",
"project_id": "4f75d991ac359f8c4c79d762",
"plan_id": "4f75d991ac359f8c4c79d762",
"vehicle_id": "4f75d991ac359f8c4c79d762",
"external_id": "ROUTE-2026-05-21-MAD03",
"start_location": {
"location_id": "4f75d991ac359f8c4c79d762",
"label": "Location label",
"country": "Spain",
"country_code": "ES",
"state": "Catalonia",
"city": "Barcelona",
"street": "Calle de Pau Claris",
"postal_code": "08302",
"comments": "Location comments",
"lat": 40.45,
"lng": -3.68,
"main_text": "Calle de Pau Claris 12",
"secondary_text": "Barcelona, Catalonia, Spain"
},
"end_location": {
"location_id": "4f75d991ac359f8c4c79d762",
"label": "Location label",
"country": "Spain",
"country_code": "ES",
"state": "Catalonia",
"city": "Barcelona",
"street": "Calle de Pau Claris",
"postal_code": "08302",
"comments": "Location comments",
"lat": 40.45,
"lng": -3.68,
"main_text": "Calle de Pau Claris 12",
"secondary_text": "Barcelona, Catalonia, Spain"
},
"label": "Eixample route — Refrigerated van 02",
"phone": "+34612345678",
"comments": "Load at 06:00 at dock 4. Depart 06:30.",
"email": "carlos.lopez@example.com",
"plate": "2596 KHO",
"vehicle_model": "Transit Custom L2H2",
"color": "#1E88E5",
"brand": "Ford",
"vehicle": {
"fuel_type": "diesel",
"consumption": 8,
"break": {
"start": 43200,
"end": 54000,
"duration": 2700
}
},
"planned_track": "spxsBsdb|Lymo`qvAx@TKvAr@K",
"is_locked": true,
"geo_fences": [
"4f75d991ac359f8c4c79d762"
],
"time_window": [
28800,
61200
],
"max_distance": 120000,
"min_distance": 5000,
"max_time": 28800,
"min_time": 3600,
"max_weight": 800,
"max_volume": 8,
"max_services": 40,
"provides": [
"refrigerated",
"lift_gate"
],
"order": 0,
"start_date": "2026-05-29T14:55:24.509Z",
"end_date": "2026-05-29T14:55:24.509Z",
"estimated_end_time": "2026-05-29T14:55:24.509Z",
"last_position": {
"lat": 40.45,
"lng": -3.68,
"created_at": "2026-05-29T14:55:24.508Z",
"orientation": 270
},
"planned_start_time": 23400,
"planned_end_time": 50400,
"custom_fields": {},
"distance_traveled": 0,
"tracing_percent": 0,
"price_per_minute": 0.0035,
"price_per_distance": 0.00045,
"toll_price": 4.8,
"toll_price_currency": "EUR",
"status": "not_started",
"created_by": "4f75d991ac359f8c4c79d762",
"created_at": "2026-05-29T14:55:24.339Z",
"updated_at": "2026-05-29T14:55:24.339Z",
"deleted_at": "2026-05-29T14:55:24.339Z",
"deleted": true,
"stops": [
{
"id": "4f75d991ac359f8c4c79d762",
"fixed_id": "1",
"organization_id": "4f75d991ac359f8c4c79d762",
"project_id": "4f75d991ac359f8c4c79d762",
"plan_id": "4f75d991ac359f8c4c79d762",
"type": "delivery",
"route_id": "4f75d991ac359f8c4c79d762",
"vehicle_id": "4f75d991ac359f8c4c79d762",
"client_id": "4f75d991ac359f8c4c79d762",
"client_external_id": "CUST-58291",
"external_id": "ORD-2026-58291",
"location": {
"location_id": "4f75d991ac359f8c4c79d762",
"label": "Location label",
"country": "Spain",
"country_code": "ES",
"state": "Catalonia",
"city": "Barcelona",
"street": "Calle de Pau Claris",
"postal_code": "08302",
"comments": "Location comments",
"lat": 40.45,
"lng": -3.68,
"main_text": "Calle de Pau Claris 12",
"secondary_text": "Barcelona, Catalonia, Spain"
},
"location_details": "Local 2, junto a la entrada principal",
"label": "Acme Pharmacy — Aragó branch",
"comments": "Ring intercom 2B. Do not leave at reception.",
"phone": "+34612345678",
"email": "sarah.johnson@example.com",
"url": "https://shop.example.com/orders/58291",
"reference_person": "Sarah Johnson",
"duration": 180,
"requires": [
"refrigerated",
"fragile"
],
"cluster": "eixample-norte",
"reward": 5,
"time_windows": [
[
28800,
61200
]
],
"volume": 0.12,
"weight": 8.4,
"max_delivery_time": 7200,
"status": "pending",
"plan_execution_date": "2026-05-29T14:55:24.491Z",
"order": 0,
"planned_arrival_time": 29500,
"planned_departure_time": 30000,
"estimated_arrival_time": "2026-05-29T14:55:24.491Z",
"estimated_departure_time": "2026-05-29T14:55:24.491Z",
"pickup_id": "4f75d991ac359f8c4c79d762",
"distance_to_previous_stop": 30000,
"distance_to_next_stop": 20000,
"optimization_warning": true,
"chain_id": "order-58291",
"chain_position": 1,
"custom_fields": {
"order_reference": "ORD-2026-58291",
"parcel_count": 2,
"cod_amount": 24.9
},
"tasks": [
{
"id": "4f75d991ac359f8c4c79d762",
"stop_id": "4f75d991ac359f8c4c79d762",
"label": "Deliver refrigerated parcel 1/2",
"comments": "Keep cold chain. Weight 12.4 kg.",
"barcode": "8410076472158",
"status": "completed",
"custom_fields": {
"sku": "SKU-4582",
"quantity": 2,
"lot_number": "L-2026-038"
},
"created_by": "4f75d991ac359f8c4c79d762",
"created_at": "2026-05-29T14:55:24.485Z",
"updated_at": "2026-05-29T14:55:24.485Z",
"deleted_at": "2026-05-29T14:55:24.485Z"
}
],
"reports": [
{
"id": "4f75d991ac359f8c4c79d762",
"stop_id": "4f75d991ac359f8c4c79d762",
"route_id": "4f75d991ac359f8c4c79d762",
"project_id": "4f75d991ac359f8c4c79d762",
"plan_id": "4f75d991ac359f8c4c79d762",
"type": "service_report_completed",
"comments": "Customer not present. Notice left in the mailbox.",
"images": [
{
"id": "4f75d991ac359f8c4c79d762",
"url": "https://api.routal.com"
}
],
"signature": {
"id": "4f75d991ac359f8c4c79d762",
"url": "https://api.routal.com"
},
"tasks": [
{
"task_id": "4f75d991ac359f8c4c79d762",
"status": "completed",
"comments": "Parcel delivered in perfect condition.",
"custom_fields": {
"sku": "SKU-4582",
"quantity": 2,
"lot_number": "L-2026-038"
}
}
],
"cancel_reason": "nobody",
"location": {
"location_id": "4f75d991ac359f8c4c79d762",
"label": "Location label",
"country": "Spain",
"country_code": "ES",
"state": "Catalonia",
"city": "Barcelona",
"street": "Calle de Pau Claris",
"postal_code": "08302",
"comments": "Location comments",
"lat": 40.45,
"lng": -3.68,
"main_text": "Calle de Pau Claris 12",
"secondary_text": "Barcelona, Catalonia, Spain"
},
"time_in_stop": 180,
"custom_fields": {
"delivered_to": "neighbor 2A",
"cod_collected": 24.9,
"photo_count": 2
},
"created_at": "2026-05-29T14:55:24.486Z"
}
],
"report_attempts": 2,
"survey": {
"stop_id": "4f75d991ac359f8c4c79d762",
"route_id": "4f75d991ac359f8c4c79d762",
"rating": 1,
"rating_tag": "time",
"comments": "The delivery was very professional and punctual.",
"created_at": "2026-05-29T14:55:24.489Z",
"updated_at": "2026-05-29T14:55:24.489Z"
},
"pin": "4729",
"customer_text_field": "Leave at reception if I'm not home.",
"supervisors": [
"4f75d991ac359f8c4c79d762"
],
"location_validation_sent": false,
"location_validation_sent_at": "2026-05-29T14:55:24.499Z",
"location_validated": false,
"location_validated_at": "2026-05-29T14:55:24.500Z",
"created_by": "4f75d991ac359f8c4c79d762",
"created_at": "2026-05-29T14:55:24.339Z",
"updated_at": "2026-05-29T14:55:24.339Z",
"deleted_at": "2026-05-29T14:55:24.339Z",
"deleted": true,
"pickup": {
"id": "4f75d991ac359f8c4c79d762",
"fixed_id": "1",
"organization_id": "4f75d991ac359f8c4c79d762",
"project_id": "4f75d991ac359f8c4c79d762",
"plan_id": "4f75d991ac359f8c4c79d762",
"type": "delivery",
"route_id": "4f75d991ac359f8c4c79d762",
"vehicle_id": "4f75d991ac359f8c4c79d762",
"client_id": "4f75d991ac359f8c4c79d762",
"client_external_id": "CUST-58291",
"external_id": "ORD-2026-58291",
"location": {
"location_id": "4f75d991ac359f8c4c79d762",
"label": "Location label",
"country": "Spain",
"country_code": "ES",
"state": "Catalonia",
"city": "Barcelona",
"street": "Calle de Pau Claris",
"postal_code": "08302",
"comments": "Location comments",
"lat": 40.45,
"lng": -3.68,
"main_text": "Calle de Pau Claris 12",
"secondary_text": "Barcelona, Catalonia, Spain"
},
"location_details": "Local 2, junto a la entrada principal",
"label": "Acme Pharmacy — Aragó branch",
"comments": "Ring intercom 2B. Do not leave at reception.",
"phone": "+34612345678",
"email": "sarah.johnson@example.com",
"url": "https://shop.example.com/orders/58291",
"reference_person": "Sarah Johnson",
"duration": 180,
"requires": [
"refrigerated",
"fragile"
],
"cluster": "eixample-norte",
"reward": 5,
"time_windows": [
[
28800,
61200
]
],
"volume": 0.12,
"weight": 8.4,
"max_delivery_time": 7200,
"status": "pending",
"plan_execution_date": "2026-05-29T14:55:24.491Z",
"order": 0,
"planned_arrival_time": 29500,
"planned_departure_time": 30000,
"estimated_arrival_time": "2026-05-29T14:55:24.491Z",
"estimated_departure_time": "2026-05-29T14:55:24.491Z",
"pickup_id": "4f75d991ac359f8c4c79d762",
"distance_to_previous_stop": 30000,
"distance_to_next_stop": 20000,
"optimization_warning": true,
"chain_id": "order-58291",
"chain_position": 1,
"custom_fields": {
"order_reference": "ORD-2026-58291",
"parcel_count": 2,
"cod_amount": 24.9
},
"tasks": [
{
"id": "4f75d991ac359f8c4c79d762",
"stop_id": "4f75d991ac359f8c4c79d762",
"label": "Deliver refrigerated parcel 1/2",
"comments": "Keep cold chain. Weight 12.4 kg.",
"barcode": "8410076472158",
"status": "completed",
"custom_fields": {
"sku": "SKU-4582",
"quantity": 2,
"lot_number": "L-2026-038"
},
"created_by": "4f75d991ac359f8c4c79d762",
"created_at": "2026-05-29T14:55:24.485Z",
"updated_at": "2026-05-29T14:55:24.485Z",
"deleted_at": "2026-05-29T14:55:24.485Z"
}
],
"reports": [
{
"id": "4f75d991ac359f8c4c79d762",
"stop_id": "4f75d991ac359f8c4c79d762",
"route_id": "4f75d991ac359f8c4c79d762",
"project_id": "4f75d991ac359f8c4c79d762",
"plan_id": "4f75d991ac359f8c4c79d762",
"type": "service_report_completed",
"comments": "Customer not present. Notice left in the mailbox.",
"images": [
{
"id": "4f75d991ac359f8c4c79d762",
"url": "https://api.routal.com"
}
],
"signature": {
"id": "4f75d991ac359f8c4c79d762",
"url": "https://api.routal.com"
},
"tasks": [
{
"task_id": "4f75d991ac359f8c4c79d762",
"status": "completed",
"comments": "Parcel delivered in perfect condition.",
"custom_fields": {
"sku": "SKU-4582",
"quantity": 2,
"lot_number": "L-2026-038"
}
}
],
"cancel_reason": "nobody",
"location": {
"location_id": "4f75d991ac359f8c4c79d762",
"label": "Location label",
"country": "Spain",
"country_code": "ES",
"state": "Catalonia",
"city": "Barcelona",
"street": "Calle de Pau Claris",
"postal_code": "08302",
"comments": "Location comments",
"lat": 40.45,
"lng": -3.68,
"main_text": "Calle de Pau Claris 12",
"secondary_text": "Barcelona, Catalonia, Spain"
},
"time_in_stop": 180,
"custom_fields": {
"delivered_to": "neighbor 2A",
"cod_collected": 24.9,
"photo_count": 2
},
"created_at": "2026-05-29T14:55:24.486Z"
}
],
"report_attempts": 2,
"survey": {
"stop_id": "4f75d991ac359f8c4c79d762",
"route_id": "4f75d991ac359f8c4c79d762",
"rating": 1,
"rating_tag": "time",
"comments": "The delivery was very professional and punctual.",
"created_at": "2026-05-29T14:55:24.489Z",
"updated_at": "2026-05-29T14:55:24.489Z"
},
"pin": "4729",
"customer_text_field": "Leave at reception if I'm not home.",
"supervisors": [
"4f75d991ac359f8c4c79d762"
],
"location_validation_sent": false,
"location_validation_sent_at": "2026-05-29T14:55:24.499Z",
"location_validated": false,
"location_validated_at": "2026-05-29T14:55:24.500Z",
"created_by": "4f75d991ac359f8c4c79d762",
"created_at": "2026-05-29T14:55:24.339Z",
"updated_at": "2026-05-29T14:55:24.339Z",
"deleted_at": "2026-05-29T14:55:24.339Z",
"deleted": true
}
}
],
"break_stop": {
"is_completed": false,
"order": 2,
"planned_start_time": 20000,
"planned_end_time": 30000,
"real_start_time": 20000,
"real_end_time": 30000
}
}{
"message": "Domain not found",
"message_id": "highway.domain.error.not_found"
}Empty
{
"message": "Domain not found",
"message_id": "highway.domain.error.not_found"
}{
"message": "Domain not found",
"message_id": "highway.domain.error.not_found"
}Empty
Empty