Route API Reference

The Route API calculates an optimized route between an origin and a destination. It supports turn-by-turn directions, toll costs, vehicle profiles, and road feature avoidance.

Endpoint: POST /solver/route

---

Overview

Route API calculates the most suitable route between an origin and a destination. With a single request, you can retrieve:

• Optimized route geometry
• Total distance and duration
• Toll costs (optional)
• Turn-by-turn directions (optional)
• Route restrictions based on vehicle properties

---

Request

Query Parameters

Parameter	Type	Required	Description
api_key	string	Optional	Your API key

Request Body

Key	Type	Required	Description
origin	Location	Yes	Starting point of the route
destination	Location	Yes	Ending point of the route
waypoints	array of Location	Optional	Intermediate waypoints for the route
departure_time	string (ISO 8601)	Optional	Planned departure time for the route
arrival_time	string (ISO 8601)	Optional	Planned arrival time for the route
section_ids	array of strings	Optional	Sections to include in the route
avoid_zones	array of coordinate polygons	Optional	Geographic zones to avoid
avoid_features	array of AvoidFeature	Optional	Road features to avoid
minimize	string	Optional	Optimization target: "distance" or "duration"
tolls	boolean	Optional	Enable toll cost calculation (default: false)
currency	string	Optional	Toll currency: "USD", "EUR", "TRY"
language	string	Optional	Language for directions: "tr-TR", "en-US" (default: "tr-TR")
direction	string	Optional	Format for direction data in each section: "geocode" returns coordinate tuples, "polyline" returns standard polyline encoded string. When null, direction is omitted. (default: "polyline")
alternatives	integer (0-5)	Optional	Number of alternative routes to return (default: 0)
action	boolean	Optional	When true, route sections will include turn-by-turn maneuver actions (default: true)
vehicle	Vehicle	Optional	Vehicle profile to use for the route

---

Location

Used in origin, destination, and waypoints.

Key	Type	Description
name	string	Location name
address	string	Street address
city	string	City name
district	string	District name
country	string	Country name
postal_code	string	Postal code
timezone	string	Timezone (e.g. "Europe/Istanbul")
latitude	number	Latitude (-90 to 90)
longitude	number	Longitude (-180 to 180)
time_window_start	string (time)	Time window start for this location (e.g. "08:00:00")
time_window_end	string (time)	Time window end for this location (e.g. "18:00:00")
location_id	string	Identifier for this location
pass_through	boolean	Whether the route should pass through this location without stopping (default: false)
stop_duration	integer	Desired duration for the stop, in seconds (0 to exclusive 50000)

Note: Address fields (address, city, etc.) can be used instead of coordinates. The API geocodes them automatically. If both are provided, coordinates take precedence.

Example:

{
  "latitude": 41.0082,
  "longitude": 28.9784,
  "name": "Sultanahmet",
  "address": "Sultanahmet Meydani",
  "city": "Istanbul",
  "district": "Fatih",
  "country": "Turkiye",
  "pass_through": false,
  "stop_duration": 300
}

---

Vehicle

Customize routing with vehicle-specific properties (useful for trucks, hazmat transport, etc.).

Key	Type	Description
vehicle_type	string	"car", "van", "truck", "motorcycle", "trailer"
fuel_type	string	"diesel", "gasoline", "electric", "hybrid", "lpg"
capacity	number >= 0	Vehicle load capacity
capacity_type	string	Unit of capacity (see below)
length	integer 0-30000	Vehicle length (cm)
width	integer 0-5000	Vehicle width (cm)
height	integer 0-5000	Vehicle height (cm)
axle_count	integer 2-255	Total number of axles
trailer_axle_count	integer >= 1	Number of trailer axles
trailer_count	integer 0-255	Number of trailers (default: 0)
tires_count	integer 0-255	Total number of tires
hazardous_goods	array of strings	Hazardous materials being transported (see below)
manufacture_year	integer	Vehicle manufacture year
brand	string	Vehicle brand
model	string	Vehicle model

capacity_type values: "weight_kg", "weight_ton", "volume_l", "volume_m3", "length", "area", "pallet", "unit"

hazardous_goods values: "explosive", "gas", "flammable", "combustible", "organic", "poison", "radioactive", "corrosive", "poisonousInhalation", "harmfulToWater", "other"

Example:

{
  "vehicle_type": "truck",
  "fuel_type": "diesel",
  "capacity": 20,
  "capacity_type": "weight_ton",
  "length": 1200,
  "width": 255,
  "height": 400,
  "axle_count": 3,
  "trailer_count": 1,
  "hazardous_goods": ["flammable"]
}

---

Avoid Feature

Road features to avoid:

Value	Description
"tunnel"	Tunnels
"ferry"	Ferry routes
"tollRoad"	Toll roads
"seasonalClosure"	Seasonally closed roads
"controlledAccessHighway"	Motorways with controlled access

---

Response

The response is an array of RouteResponseModel objects.

RouteResponseModel

Key	Type	Required	Description
id	string	Yes	Unique route identifier
status	string	No	Route status: "created", "planned", "in_progress", "completed", "cancelled"
departure_time	string (ISO 8601)	No	Departure time
arrival_time	string (ISO 8601)	No	Arrival time
summary	Summary	No	Overall route summary
sections	array of Section	No	Individual route sections

Summary

Key	Type	Required	Description
distance	number	Yes	Total distance (meters)
duration	number	Yes	Total duration (seconds)
cost	number	No	Total toll cost (if tolls: true)

Section

Key	Type	Required	Description
id	string	Yes	Section identifier
company_id	string	Yes	Company identifier
distance	number	Yes	Section distance (meters)
duration	number	Yes	Section duration (seconds)
route_section_code	string	No	Cached section code
origin_id	string	No	Origin location identifier
destination_id	string	No	Destination location identifier
vehicle_profile_id	string	No	Vehicle profile identifier
cost	number	No	Section toll cost
directions	string or array or null	No	Route geometry (see note below)
actions	array of Action	No	Turn-by-turn maneuvers
tolls	Tolls	No	Detailed toll information
origin	object	No	Section start location
destination	object	No	Section end location
branch_id	string	No	Branch identifier
created_at	string (ISO 8601)	No	Creation timestamp
updated_at	string (ISO 8601)	No	Last update timestamp

Note: The directions field format depends on the direction request body parameter: - "polyline" -> encoded polyline string - "geocode" -> [[lat, lon], ...] coordinate array - null -> direction data is omitted

---

Action (Turn-by-Turn)

Key	Type	Description
action	string	Maneuver type (see below)
direction	string	Turn direction: "left", "right", "middle"
severity	string	Maneuver difficulty (see below)
instruction	string	Human-readable instruction
offset	number	Distance from section start (meters)
duration	number	Maneuver duration (seconds)
length	number	Maneuver length (meters)

action values: "depart", "arrive", "continue", "turn", "ramp", "exit", "roundaboutEnter", "roundaboutExit", "roundaboutPass", "uTurn", "keep", "enterHighway", "continueHighway", "board", "charging", "chargingSetup"

direction values: "left", "right", "middle"

severity values: "light", "quite", "heavy", "quiteNormal", "normal", "quiteDifficult", "difficult" -- from gentle (light) to sharp (difficult)

---

Tolls

Tolls object

Key	Type	Description
toll_systems	array of TollSystem	Toll systems on the route
toll_costs	array of TollCost	Cost breakdown per system
summary	TollSummary	Total cost summary

TollSystem

Key	Type	Description
id	integer	Toll system identifier
name	string	Toll system name

TollSummary

Key	Type	Description
total	number	Total toll cost
currency	string	Currency code

TollCost

Key	Type	Description
toll_system	string	The toll system this cost applies to
toll_system_names	array of strings	Names of the toll system
fares	array of Fare	Individual fares
country_code	string	ISO country code

Fare

Key	Type	Description
id	string	Fare identifier
name	string	Fare description
price	number	Fare amount
currency	string	Currency code
estimated	boolean	Whether the cost is estimated
reason	string	Reason this fare applies

---

Examples

Minimal request

curl -X POST "https://api.flio.ai/solver/route?api_key=YOUR-API-KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "origin": {
      "latitude": 41.0082,
      "longitude": 28.9784
    },
    "destination": {
      "latitude": 41.0150,
      "longitude": 28.9850
    }
  }'

Full request

{
  "origin": {
    "latitude": 41.0082,
    "longitude": 28.9784,
    "name": "Sultanahmet",
    "address": "Sultanahmet Meydani",
    "city": "Istanbul"
  },
  "destination": {
    "latitude": 41.0150,
    "longitude": 28.9850,
    "name": "Taksim",
    "address": "Taksim Meydani",
    "city": "Istanbul"
  },
  "waypoints": [
    {
      "latitude": 41.0100,
      "longitude": 28.9800,
      "stop_duration": 300,
      "pass_through": false
    }
  ],
  "departure_time": "2026-07-20T08:00:00Z",
  "minimize": "duration",
  "tolls": true,
  "currency": "TRY",
  "language": "tr-TR",
  "direction": "polyline",
  "action": true,
  "alternatives": 1,
  "avoid_features": ["tollRoad", "ferry"],
  "avoid_zones": [
    [[41.01, 28.97], [41.02, 28.97], [41.02, 28.98], [41.01, 28.98], [41.01, 28.97]]
  ],
  "vehicle": {
    "vehicle_type": "truck",
    "fuel_type": "diesel",
    "capacity": 20,
    "capacity_type": "weight_ton",
    "length": 1200,
    "width": 255,
    "height": 400,
    "axle_count": 3,
    "trailer_count": 1,
    "hazardous_goods": ["flammable"]
  }
}

Python

import requests

API_BASE_URL = "https://api.flio.ai"
API_KEY = "YOUR-API-KEY"

payload = {
    "origin": {
        "latitude": 41.0082,
        "longitude": 28.9784
    },
    "destination": {
        "latitude": 41.0150,
        "longitude": 28.9850
    },
    "minimize": "duration",
    "tolls": True,
    "currency": "TRY",
    "language": "tr-TR",
    "direction": "polyline",
    "action": True
}

response = requests.post(
    f"{API_BASE_URL}/solver/route?api_key={API_KEY}",
    json=payload
)
routes = response.json()

route = routes[0]
print(f"Route ID: {route['id']}")
print(f"Distance: {route['summary']['distance']} m")
print(f"Duration: {route['summary']['duration']} s")

cURL

curl -X POST "https://api.flio.ai/solver/route?api_key=YOUR-API-KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "origin": { "latitude": 41.0082, "longitude": 28.9784 },
    "destination": { "latitude": 41.0150, "longitude": 28.9850 },
    "minimize": "duration",
    "tolls": true,
    "currency": "TRY",
    "direction": "polyline",
    "action": true
  }'

---

Route API reference -- Flio.ai

Next Steps

• Route Overview
• Route Features
• Route Examples