{"openapi":"3.1.0","info":{"title":"EasyRoute API","summary":"Optimize multi-stop routes, search addresses and share routes.","description":"Send your API key as `Authorization: Bearer <key>`. Create keys in the web app: Account, API keys. Limits follow the plan of the account that owns the key.","version":"1.0.0"},"servers":[{"url":"https://easyroute.ae"}],"paths":{"/api/v1/optimize":{"post":{"tags":["EasyRoute API"],"summary":"Optimize a multi-stop route","description":"Puts the stops in a shorter order and gives a time for each. Counts as one optimization of the account's day on the free plan.","operationId":"optimize_api_v1_optimize_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OptimizeIn"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OptimizeOut"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"402":{"description":"A limit of the plan: limit_stops, limit_daily or pro_required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"The request is not valid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests. Retry-After says how long to wait.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/geocode":{"get":{"tags":["EasyRoute API"],"summary":"Search for an address","operationId":"geocode_api_v1_geocode_get","parameters":[{"name":"q","in":"query","required":true,"schema":{"type":"string","maxLength":240,"description":"Search text, 2 to 120 characters.","title":"Q"},"description":"Search text, 2 to 120 characters."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":8,"minimum":1,"description":"How many results.","default":5,"title":"Limit"},"description":"How many results."},{"name":"lat","in":"query","required":false,"schema":{"anyOf":[{"type":"number","maximum":90,"minimum":-90},{"type":"null"}],"description":"Bias results towards this latitude.","title":"Lat"},"description":"Bias results towards this latitude."},{"name":"lon","in":"query","required":false,"schema":{"anyOf":[{"type":"number","maximum":180,"minimum":-180},{"type":"null"}],"description":"Bias results towards this longitude.","title":"Lon"},"description":"Bias results towards this longitude."},{"name":"lang","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":16},{"type":"null"}],"description":"Result language: en, de, fr or it.","title":"Lang"},"description":"Result language: en, de, fr or it."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GeocodeOut"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"402":{"description":"A limit of the plan: limit_stops, limit_daily or pro_required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"The request is not valid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests. Retry-After says how long to wait.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Address search is not available right now.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/routes/link":{"post":{"tags":["EasyRoute API"],"summary":"Make a link a driver can open","description":"Stores a snapshot of the route and returns a link. The person who opens it needs no app and no account. Any plan.","operationId":"route_link_api_v1_routes_link_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LinkIn"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LinkOut"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"402":{"description":"A limit of the plan: limit_stops, limit_daily or pro_required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"The request is not valid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests. Retry-After says how long to wait.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/usage":{"get":{"tags":["EasyRoute API"],"summary":"Plan, limits and today's use","operationId":"usage_api_v1_usage_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UsageOut"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"402":{"description":"A limit of the plan: limit_stops, limit_daily or pro_required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"The request is not valid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Too many requests. Retry-After says how long to wait.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}}},"components":{"schemas":{"ApiPlace":{"properties":{"lat":{"type":"number","maximum":90.0,"minimum":-90.0,"title":"Lat","description":"Latitude in degrees, -90 to 90.","examples":[25.2048]},"lon":{"type":"number","maximum":180.0,"minimum":-180.0,"title":"Lon","description":"Longitude in degrees, -180 to 180.","examples":[55.2708]},"name":{"type":"string","maxLength":120,"title":"Name","description":"Optional label for the place.","default":""}},"type":"object","required":["lat","lon"],"title":"ApiPlace"},"ApiStop":{"properties":{"id":{"anyOf":[{"type":"string","maxLength":64,"minLength":1},{"type":"null"}],"title":"Id","description":"Your own id for the stop (1 to 64 characters, unique in the request). Generated as stop-1, stop-2 and so on when left out."},"name":{"type":"string","maxLength":120,"title":"Name","description":"Optional name, returned unchanged.","default":""},"address":{"type":"string","maxLength":200,"title":"Address","description":"Optional address, returned unchanged.","default":""},"lat":{"type":"number","maximum":90.0,"minimum":-90.0,"title":"Lat","description":"Latitude in degrees."},"lon":{"type":"number","maximum":180.0,"minimum":-180.0,"title":"Lon","description":"Longitude in degrees."},"service_s":{"type":"integer","maximum":86400.0,"minimum":0.0,"title":"Service S","description":"Seconds spent at the stop.","default":0},"window":{"anyOf":[{"$ref":"#/components/schemas/TimeWindow"},{"type":"null"}],"description":"Time window {start, end} (ISO-8601 with offset). Needs Pro."},"priority":{"type":"string","enum":["normal","first","last"],"title":"Priority","description":"Visit this stop first or last. Needs Pro.","default":"normal"}},"type":"object","required":["lat","lon"],"title":"ApiStop"},"ErrorBody":{"properties":{"code":{"type":"string","title":"Code","description":"Stable machine code: unauthorized, invalid, pro_required, limit_stops, limit_daily, limit_handoffs, rate_limited, unavailable, not_found or server."},"message":{"type":"string","title":"Message","description":"One plain sentence for a person."},"limit":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Limit","description":"For limit errors: which limit, its value and the plan."},"upgrade_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Upgrade Url","description":"For limit errors: where to upgrade."}},"type":"object","required":["code","message"],"title":"ErrorBody"},"ErrorEnvelope":{"properties":{"error":{"$ref":"#/components/schemas/ErrorBody"}},"type":"object","required":["error"],"title":"ErrorEnvelope"},"GeoPlace":{"properties":{"name":{"type":"string","title":"Name"},"address":{"type":"string","title":"Address"},"lat":{"type":"number","title":"Lat"},"lon":{"type":"number","title":"Lon"}},"type":"object","required":["name","address","lat","lon"],"title":"GeoPlace"},"GeocodeOut":{"properties":{"results":{"items":{"$ref":"#/components/schemas/GeoPlace"},"type":"array","title":"Results"}},"type":"object","required":["results"],"title":"GeocodeOut"},"HandoffStart":{"properties":{"name":{"type":"string","maxLength":120,"title":"Name","default":""},"lat":{"type":"number","maximum":90.0,"minimum":-90.0,"title":"Lat"},"lon":{"type":"number","maximum":180.0,"minimum":-180.0,"title":"Lon"}},"type":"object","required":["lat","lon"],"title":"HandoffStart"},"HandoffTotals":{"properties":{"distance_m":{"type":"integer","maximum":100000000.0,"minimum":0.0,"title":"Distance M"},"duration_s":{"type":"integer","maximum":10000000.0,"minimum":0.0,"title":"Duration S"}},"type":"object","required":["distance_m","duration_s"],"title":"HandoffTotals"},"LinkIn":{"properties":{"title":{"type":"string","maxLength":120,"title":"Title","description":"Title shown on the link page.","default":"EasyRoute route"},"start":{"anyOf":[{"$ref":"#/components/schemas/HandoffStart"},{"type":"null"}],"description":"Where the route starts."},"end_mode":{"type":"string","enum":["round_trip","open"],"title":"End Mode","default":"round_trip"},"profile":{"type":"string","enum":["car","bike","walk"],"title":"Profile","default":"car"},"stops":{"items":{"$ref":"#/components/schemas/LinkStop"},"type":"array","maxItems":1000,"minItems":1,"title":"Stops","description":"The stops in the order to drive them."},"totals":{"anyOf":[{"$ref":"#/components/schemas/HandoffTotals"},{"type":"null"}],"description":"Optional {distance_m, duration_s} shown on the page."}},"type":"object","required":["stops"],"title":"LinkIn"},"LinkOut":{"properties":{"id":{"type":"string","title":"Id"},"url":{"type":"string","title":"Url","description":"Anyone with this address can open the route, without an app or an account."},"expires":{"type":"string","title":"Expires"}},"type":"object","required":["id","url","expires"],"title":"LinkOut"},"LinkStop":{"properties":{"id":{"anyOf":[{"type":"string","maxLength":64,"minLength":1},{"type":"null"}],"title":"Id","description":"Your id for the stop; generated when left out."},"name":{"type":"string","maxLength":120,"title":"Name","default":""},"address":{"type":"string","maxLength":200,"title":"Address","default":""},"lat":{"type":"number","maximum":90.0,"minimum":-90.0,"title":"Lat"},"lon":{"type":"number","maximum":180.0,"minimum":-180.0,"title":"Lon"},"note":{"type":"string","maxLength":300,"title":"Note","default":""},"service_s":{"type":"integer","maximum":86400.0,"minimum":0.0,"title":"Service S","default":0},"eta":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Eta","description":"Planned arrival (ISO-8601 with offset)."}},"type":"object","required":["lat","lon"],"title":"LinkStop"},"OptimizeIn":{"properties":{"start":{"$ref":"#/components/schemas/ApiPlace","description":"Where the route starts."},"end_mode":{"type":"string","enum":["round_trip","open"],"title":"End Mode","description":"round_trip returns to the start; open ends at the last stop.","default":"round_trip"},"departure":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Departure","description":"Departure time (ISO-8601 with offset). Defaults to now."},"profile":{"type":"string","enum":["car","bike","walk"],"title":"Profile","description":"How the route is travelled.","default":"car"},"stops":{"items":{"$ref":"#/components/schemas/ApiStop"},"type":"array","minItems":1,"title":"Stops","description":"The stops, in any order."}},"type":"object","required":["start","stops"],"title":"OptimizeIn"},"OptimizeOut":{"properties":{"stops":{"items":{"$ref":"#/components/schemas/RouteStop"},"type":"array","title":"Stops","description":"The stops in the order to visit them."},"start":{"$ref":"#/components/schemas/ApiPlace"},"end_mode":{"type":"string","enum":["round_trip","open"],"title":"End Mode"},"profile":{"type":"string","enum":["car","bike","walk"],"title":"Profile"},"departure":{"type":"string","title":"Departure"},"return_leg":{"anyOf":[{"$ref":"#/components/schemas/ReturnLeg"},{"type":"null"}],"description":"The way back to the start; null for an open route."},"total_distance_m":{"type":"integer","title":"Total Distance M"},"total_duration_s":{"type":"integer","title":"Total Duration S"},"finish":{"type":"string","title":"Finish","description":"When the route ends (ISO-8601)."},"savings":{"$ref":"#/components/schemas/Savings"},"solver":{"type":"string","title":"Solver"},"matrix":{"type":"string","title":"Matrix","description":"osrm for road distances, haversine for the built-in model (estimates)."},"usage":{"$ref":"#/components/schemas/UsageOut"}},"type":"object","required":["stops","start","end_mode","profile","departure","return_leg","total_distance_m","total_duration_s","finish","savings","solver","matrix","usage"],"title":"OptimizeOut"},"ReturnLeg":{"properties":{"distance_m":{"type":"integer","title":"Distance M"},"duration_s":{"type":"integer","title":"Duration S"}},"type":"object","required":["distance_m","duration_s"],"title":"ReturnLeg"},"RouteStop":{"properties":{"id":{"type":"string","title":"Id"},"name":{"type":"string","title":"Name"},"address":{"type":"string","title":"Address"},"lat":{"type":"number","title":"Lat"},"lon":{"type":"number","title":"Lon"},"eta":{"type":"string","title":"Eta","description":"Arrival time (ISO-8601)."},"departure":{"type":"string","title":"Departure","description":"Time of leaving the stop (ISO-8601)."},"distance_m":{"type":"integer","title":"Distance M","description":"Metres from the previous point."},"duration_s":{"type":"integer","title":"Duration S","description":"Seconds of travel from the previous point."},"wait_s":{"type":"integer","title":"Wait S","description":"Seconds waited for a time window to open."},"late_s":{"type":"integer","title":"Late S","description":"Seconds after the end of the time window (0 when on time)."}},"type":"object","required":["id","name","address","lat","lon","eta","departure","distance_m","duration_s","wait_s","late_s"],"title":"RouteStop"},"Savings":{"properties":{"distance_m":{"type":"integer","title":"Distance M","description":"Metres saved compared with the order you sent. Never negative."},"duration_s":{"type":"integer","title":"Duration S","description":"Seconds of travel saved. Never negative."},"percent_shorter":{"type":"number","title":"Percent Shorter","description":"Percent of the distance saved."},"meaningful":{"type":"boolean","title":"Meaningful","description":"True when at least 3 percent and 300 m were saved."}},"type":"object","required":["distance_m","duration_s","percent_shorter","meaningful"],"title":"Savings"},"TimeWindow":{"properties":{"start":{"type":"string","format":"date-time","title":"Start"},"end":{"type":"string","format":"date-time","title":"End"}},"type":"object","required":["start","end"],"title":"TimeWindow"},"UsageLimits":{"properties":{"max_stops":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Max Stops","description":"Stops per route, or null (no limit of the plan)."},"stops_ceiling":{"type":"integer","title":"Stops Ceiling","description":"Technical fair-use ceiling of stops per route, on every plan."},"optimizations_per_day":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Optimizations Per Day","description":"Optimizations per UTC day, or null (no limit of the plan)."},"optimizations_left_today":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Optimizations Left Today"},"resets_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Resets At","description":"When the daily count resets (ISO-8601), or null."}},"type":"object","required":["max_stops","stops_ceiling","optimizations_per_day","optimizations_left_today","resets_at"],"title":"UsageLimits"},"UsageOut":{"properties":{"plan":{"type":"string","enum":["free","pro"],"title":"Plan"},"limits":{"$ref":"#/components/schemas/UsageLimits"},"used_today":{"type":"integer","title":"Used Today","description":"Optimizations counted today (UTC) for this account, in the apps and through the API."},"requests_per_minute":{"type":"integer","title":"Requests Per Minute","description":"Requests a minute allowed per API key."},"upgrade_url":{"type":"string","title":"Upgrade Url"}},"type":"object","required":["plan","limits","used_today","requests_per_minute","upgrade_url"],"title":"UsageOut"}},"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer"}}},"security":[{"bearerAuth":[]}]}