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
`apiKey`	string	Optional	Your API key
`direction`	string	Optional	Geometry format: `"geocode"` (coordinate array) or `"polyline"` (encoded polyline string). If omitted, `directions` is returned as `null`.

Request Body¶

Key	Type	Required	Description
`origin`	Location	Yes	Starting point
`destination`	Location	Yes	Destination point
`waypoints`	array of Location	Optional	Intermediate stops
`departureTime`	string (ISO 8601)	Optional	Planned departure time
`arrivalTime`	string (ISO 8601)	Optional	Planned arrival time
`section_ids`	array of strings	Optional	Cached section IDs to include
`avoidAreas`	array of coordinate polygons	Optional	Geographic areas to avoid
`avoidFeatures`	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	Turn-by-turn directions language
`vehicle`	Vehicle	Optional	Vehicle profile for truck routing

Location¶

Used in origin, destination, and waypoints.

Key	Type	Description
`latitude`	number	Latitude (−90 to 90)
`longitude`	number	Longitude (−180 to 180)
`address`	string	Street address
`city`	string	City name
`district`	string	District name
`country`	string	Country name
`postalCode`	string	Postal code
`timezone`	string	Timezone (e.g. `"Europe/Istanbul"`)
`location_id`	string	Optional identifier for this location
`pass_through`	boolean	If `true`, the route passes through without stopping
`stopDuration`	integer	Stop duration at this location (seconds, 0–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,
  "address": "Sultanahmet Meydanı",
  "city": "İstanbul",
  "district": "Fatih",
  "country": "Türkiye"
}

Vehicle¶

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

Key	Type	Description
`vehicleType`	string	`"car"`, `"van"`, `"truck"`, `"motorcycle"`, `"trailer"`
`fuelType`	string	`"diesel"`, `"gasoline"`, `"electric"`, `"hybrid"`, `"lpg"`
`capacity`	number ≥ 0	Vehicle load capacity
`capacityType`	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
`tires_count`	integer 0–255	Total number of tires
`hazardousGoods`	array of strings	Hazardous materials being transported (see below)
`manufactureYear`	integer	Vehicle manufacture year
`brand`	string	Vehicle brand
`model`	string	Vehicle model

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

hazardousGoods values: "explosive", "gas", "flammable", "combustible", "organic", "poison", "radioactive", "corrosive", "poisonous_inhalation", "harmful_to_water", "other"

Example:

{
  "vehicleType": "truck",
  "fuelType": "diesel",
  "capacity": 20,
  "capacityType": "weight_ton",
  "length": 1200,
  "width": 255,
  "height": 400,
  "axle_count": 3,
  "trailer_count": 1,
  "hazardousGoods": ["flammable"]
}

Avoid Feature¶

Road features to avoid. Values use camelCase:

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

Response¶

Top-level¶

Key	Type	Description
`id`	string	Unique request identifier
`routes`	array of Route	Calculated routes

Route¶

Key	Type	Description
`summary`	Summary	Overall route summary
`sections`	array of Section	Individual route sections

Summary¶

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

Section¶

Key	Type	Description
`id`	string	Section identifier
`distance`	number	Section distance (meters)
`duration`	number	Section duration (seconds)
`cost`	number	Section toll cost
`origin`	object	Section start location
`destination`	object	Section end location
`steps`	array of Step	Turn-by-turn maneuvers
`tolls`	Tolls	Detailed toll information
`directions`	string or array	Route geometry (see note below)
`routeSectionCode`	string	Cached section code

Note: The directions field format depends on the direction query parameter: - "polyline" → encoded polyline string - "geocode" → [[lat, lon], ...] coordinate array - omitted → null

Step (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`	integer	Distance from section start (meters)
`duration`	integer	Maneuver duration (seconds)
`length`	integer	Maneuver length (meters)

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

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

Tolls¶

Tolls object¶

Key	Type	Description
`tollSystems`	array	Toll systems on the route
`tollCosts`	array	Cost breakdown per system
`summary`	object	Total cost summary

Summary¶

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

TollCost entry¶

Key	Type	Description
`tollSystem`	object	The toll system this cost applies to
`fares`	array of Fare	Individual fares
`countryCode`	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¶

{
  "origin": {
    "latitude": 41.0082,
    "longitude": 28.9784
  },
  "destination": {
    "latitude": 41.0150,
    "longitude": 28.9850
  }
}

Full request¶

{
  "origin": {
    "latitude": 41.0082,
    "longitude": 28.9784,
    "address": "Sultanahmet Meydanı",
    "city": "İstanbul"
  },
  "destination": {
    "latitude": 41.0150,
    "longitude": 28.9850,
    "address": "Taksim Meydanı",
    "city": "İstanbul"
  },
  "waypoints": [
    {
      "latitude": 41.0100,
      "longitude": 28.9800,
      "stopDuration": 300
    }
  ],
  "minimize": "duration",
  "tolls": true,
  "currency": "TRY",
  "language": "tr-TR",
  "avoidFeatures": ["tollRoad", "ferry"]
}

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"
}

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

print(f"Distance: {result['routes'][0]['summary']['distance']} m")
print(f"Duration: {result['routes'][0]['summary']['duration']} s")

cURL¶

curl -X POST "https://api.flio.ai/solver/route?apiKey=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
  }'

Route API reference — Flio.ai

Route API Reference¶

Overview¶

Request¶

Query Parameters¶

Request Body¶

Location¶

Vehicle¶

Avoid Feature¶

Response¶

Top-level¶

Route¶

Summary¶

Section¶

Step (Turn-by-Turn)¶

Tolls¶

Tolls object¶

Summary¶

TollCost entry¶

Fare¶

Examples¶

Minimal request¶

Full request¶

Python¶

cURL¶

Next Steps¶