{"openapi":"3.1.0","info":{"title":"VEZOO Public API","version":"1.0.0","description":"Routing, geocoding, route autocomplete, roadside POIs and smart trip planning."},"externalDocs":{"description":"VEZOO API documentation","url":"https:\/\/vezoo.ru\/api"},"servers":[{"url":"https:\/\/vezoo.ru\/api\/v1"}],"tags":[{"name":"Locations","description":"Autocomplete and geocoding."},{"name":"Routing","description":"Road route calculation."},{"name":"Trip data","description":"POIs and smart stops along a calculated route."}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"VEZOO API key","description":"Use Authorization: Bearer <api-key>."}},"headers":{"ApiVersion":{"description":"API version used for the response.","schema":{"type":"string","example":"v1"}},"RequestId":{"description":"Unique request identifier for support and diagnostics.","schema":{"type":"string","format":"uuid"}},"RateLimitLimit":{"description":"Effective per-minute request limit.","schema":{"type":"integer"}},"RateLimitRemaining":{"description":"Requests remaining in the current minute.","schema":{"type":"integer"}},"QuotaLimit":{"description":"Total request quota when configured for the API key.","schema":{"type":"integer"}},"QuotaRemaining":{"description":"Requests remaining in the configured total quota.","schema":{"type":"integer"}},"RetryAfter":{"description":"Seconds before retrying a rate-limited request.","schema":{"type":"integer"}}},"schemas":{"Error":{"type":"object","required":["success","error","error_code"],"properties":{"success":{"type":"boolean","const":false},"error":{"type":"string"},"error_code":{"type":"string","examples":["invalid_api_key","scope_forbidden","rate_limit_exceeded"]}}},"ValidationError":{"type":"object","required":["message","errors"],"properties":{"message":{"type":"string"},"errors":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}}}}},"City":{"type":"object","properties":{"id":{"type":["integer","null"]},"name":{"type":"string"},"slug":{"type":"string"},"admin_area":{"type":["string","null"]},"country":{"type":["string","null"]},"country_code":{"type":["string","null"]},"latitude":{"type":["number","null"]},"longitude":{"type":["number","null"]},"routing_region":{"type":["string","null"]}}},"RouteResult":{"type":"object","description":"Calculated route payload. Polyline can be passed directly to places\/along-route and trip-insights.","properties":{"kilometers":{"type":"number"},"minutes":{"type":"number"},"polyline":{"type":"string","description":"Encoded route polyline."},"segments":{"type":"array","items":{"type":"object","additionalProperties":true}}},"additionalProperties":true},"PlaceCategory":{"type":"string","enum":["fuel","food","lodging","service","tyres","parking","charging"]}}},"paths":{"\/cities":{"get":{"tags":["Locations"],"summary":"Search route locations","operationId":"searchCities","security":[{"BearerAuth":[]}],"x-vezoo-scope":"cities","x-rate-limit-per-minute":120,"parameters":[{"name":"q","in":"query","required":true,"description":"Location query, at least 2 characters.","schema":{"type":"string","minLength":2,"maxLength":80}},{"name":"limit","in":"query","required":false,"description":"Maximum number of suggestions.","schema":{"type":"integer","minimum":1,"maximum":20,"default":10}}],"responses":{"200":{"description":"Matching locations.","headers":{"X-API-Version":{"$ref":"#\/components\/headers\/ApiVersion"},"X-Request-Id":{"$ref":"#\/components\/headers\/RequestId"},"X-RateLimit-Limit":{"$ref":"#\/components\/headers\/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#\/components\/headers\/RateLimitRemaining"},"X-Quota-Limit":{"$ref":"#\/components\/headers\/QuotaLimit"},"X-Quota-Remaining":{"$ref":"#\/components\/headers\/QuotaRemaining"}},"content":{"application\/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"query":{"type":"string"},"cities":{"type":"array","items":{"$ref":"#\/components\/schemas\/City"}}}}}}},"401":{"description":"Missing, invalid, disabled or expired API key.","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"403":{"description":"The key does not allow this scope or browser origin.","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"422":{"description":"Request validation failed.","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/ValidationError"}}}},"429":{"description":"Rate limit or total quota exceeded.","headers":{"Retry-After":{"$ref":"#\/components\/headers\/RetryAfter"},"X-API-Version":{"$ref":"#\/components\/headers\/ApiVersion"},"X-Request-Id":{"$ref":"#\/components\/headers\/RequestId"},"X-RateLimit-Limit":{"$ref":"#\/components\/headers\/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#\/components\/headers\/RateLimitRemaining"},"X-Quota-Limit":{"$ref":"#\/components\/headers\/QuotaLimit"},"X-Quota-Remaining":{"$ref":"#\/components\/headers\/QuotaRemaining"}},"content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"503":{"description":"Public API or a required routing service is temporarily unavailable.","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}}}}},"\/geocode":{"get":{"tags":["Locations"],"summary":"Forward or reverse geocode a location","description":"Use q for forward geocoding, or provide both lat and lon for reverse geocoding.","operationId":"geocode","security":[{"BearerAuth":[]}],"x-vezoo-scope":"geocode","x-rate-limit-per-minute":30,"parameters":[{"name":"q","in":"query","required":false,"schema":{"type":"string","minLength":2,"maxLength":120}},{"name":"lat","in":"query","required":false,"schema":{"type":"number","minimum":-90,"maximum":90}},{"name":"lon","in":"query","required":false,"schema":{"type":"number","minimum":-180,"maximum":180}}],"responses":{"200":{"description":"Resolved location.","headers":{"X-API-Version":{"$ref":"#\/components\/headers\/ApiVersion"},"X-Request-Id":{"$ref":"#\/components\/headers\/RequestId"},"X-RateLimit-Limit":{"$ref":"#\/components\/headers\/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#\/components\/headers\/RateLimitRemaining"},"X-Quota-Limit":{"$ref":"#\/components\/headers\/QuotaLimit"},"X-Quota-Remaining":{"$ref":"#\/components\/headers\/QuotaRemaining"}},"content":{"application\/json":{"schema":{"type":"object","additionalProperties":true}}}},"404":{"description":"Location not found.","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"401":{"description":"Missing, invalid, disabled or expired API key.","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"403":{"description":"The key does not allow this scope or browser origin.","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"422":{"description":"Request validation failed.","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/ValidationError"}}}},"429":{"description":"Rate limit or total quota exceeded.","headers":{"Retry-After":{"$ref":"#\/components\/headers\/RetryAfter"},"X-API-Version":{"$ref":"#\/components\/headers\/ApiVersion"},"X-Request-Id":{"$ref":"#\/components\/headers\/RequestId"},"X-RateLimit-Limit":{"$ref":"#\/components\/headers\/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#\/components\/headers\/RateLimitRemaining"},"X-Quota-Limit":{"$ref":"#\/components\/headers\/QuotaLimit"},"X-Quota-Remaining":{"$ref":"#\/components\/headers\/QuotaRemaining"}},"content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"503":{"description":"Public API or a required routing service is temporarily unavailable.","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}}}}},"\/route":{"get":{"tags":["Routing"],"summary":"Calculate a road route","operationId":"calculateRouteGet","security":[{"BearerAuth":[]}],"x-vezoo-scope":"route","x-rate-limit-per-minute":60,"parameters":[{"name":"from","in":"query","required":true,"schema":{"type":"string","minLength":2,"maxLength":120}},{"name":"to","in":"query","required":true,"schema":{"type":"string","minLength":2,"maxLength":120}},{"name":"v","in":"query","required":false,"description":"Up to 12 semicolon-separated intermediate points.","schema":{"type":"string","maxLength":1600}},{"name":"exclude","in":"query","required":false,"description":"Comma-separated exclusions: toll,motorway,ferry.","schema":{"type":"string"}}],"responses":{"200":{"description":"Calculated route.","headers":{"X-API-Version":{"$ref":"#\/components\/headers\/ApiVersion"},"X-Request-Id":{"$ref":"#\/components\/headers\/RequestId"},"X-RateLimit-Limit":{"$ref":"#\/components\/headers\/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#\/components\/headers\/RateLimitRemaining"},"X-Quota-Limit":{"$ref":"#\/components\/headers\/QuotaLimit"},"X-Quota-Remaining":{"$ref":"#\/components\/headers\/QuotaRemaining"}},"content":{"application\/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"from":{"type":"string"},"to":{"type":"string"},"via":{"type":"array","items":{"type":"string"}},"exclude":{"type":"array","items":{"type":"string","enum":["toll","motorway","ferry"]}},"route":{"$ref":"#\/components\/schemas\/RouteResult"}}}}}},"404":{"description":"Unknown location or no route found.","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"401":{"description":"Missing, invalid, disabled or expired API key.","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"403":{"description":"The key does not allow this scope or browser origin.","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"422":{"description":"Request validation failed.","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/ValidationError"}}}},"429":{"description":"Rate limit or total quota exceeded.","headers":{"Retry-After":{"$ref":"#\/components\/headers\/RetryAfter"},"X-API-Version":{"$ref":"#\/components\/headers\/ApiVersion"},"X-Request-Id":{"$ref":"#\/components\/headers\/RequestId"},"X-RateLimit-Limit":{"$ref":"#\/components\/headers\/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#\/components\/headers\/RateLimitRemaining"},"X-Quota-Limit":{"$ref":"#\/components\/headers\/QuotaLimit"},"X-Quota-Remaining":{"$ref":"#\/components\/headers\/QuotaRemaining"}},"content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"503":{"description":"Public API or a required routing service is temporarily unavailable.","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}}}},"post":{"tags":["Routing"],"summary":"Calculate a road route using JSON","operationId":"calculateRoutePost","security":[{"BearerAuth":[]}],"x-vezoo-scope":"route","x-rate-limit-per-minute":60,"requestBody":{"required":true,"content":{"application\/json":{"schema":{"type":"object","required":["from","to"],"properties":{"from":{"type":"string","minLength":2,"maxLength":120},"to":{"type":"string","minLength":2,"maxLength":120},"vias":{"type":"array","maxItems":12,"items":{"type":"string","minLength":2,"maxLength":120}},"exclude":{"oneOf":[{"type":"string","description":"Comma-separated: toll,motorway,ferry"},{"type":"array","items":{"type":"string","enum":["toll","motorway","ferry"]}}]}},"example":{"from":"\u041c\u043e\u0441\u043a\u0432\u0430","to":"\u041a\u0430\u0437\u0430\u043d\u044c","vias":["\u0412\u043b\u0430\u0434\u0438\u043c\u0438\u0440"],"exclude":["ferry"]}}}}},"responses":{"200":{"description":"Calculated route.","headers":{"X-API-Version":{"$ref":"#\/components\/headers\/ApiVersion"},"X-Request-Id":{"$ref":"#\/components\/headers\/RequestId"},"X-RateLimit-Limit":{"$ref":"#\/components\/headers\/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#\/components\/headers\/RateLimitRemaining"},"X-Quota-Limit":{"$ref":"#\/components\/headers\/QuotaLimit"},"X-Quota-Remaining":{"$ref":"#\/components\/headers\/QuotaRemaining"}},"content":{"application\/json":{"schema":{"type":"object","additionalProperties":true}}}},"404":{"description":"Unknown location or no route found.","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"401":{"description":"Missing, invalid, disabled or expired API key.","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"403":{"description":"The key does not allow this scope or browser origin.","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"422":{"description":"Request validation failed.","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/ValidationError"}}}},"429":{"description":"Rate limit or total quota exceeded.","headers":{"Retry-After":{"$ref":"#\/components\/headers\/RetryAfter"},"X-API-Version":{"$ref":"#\/components\/headers\/ApiVersion"},"X-Request-Id":{"$ref":"#\/components\/headers\/RequestId"},"X-RateLimit-Limit":{"$ref":"#\/components\/headers\/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#\/components\/headers\/RateLimitRemaining"},"X-Quota-Limit":{"$ref":"#\/components\/headers\/QuotaLimit"},"X-Quota-Remaining":{"$ref":"#\/components\/headers\/QuotaRemaining"}},"content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"503":{"description":"Public API or a required routing service is temporarily unavailable.","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}}}}},"\/places\/along-route":{"post":{"tags":["Trip data"],"summary":"Get POIs along an encoded route","description":"Pass route.polyline returned by \/route. Categories default to all supported categories.","operationId":"placesAlongRoute","security":[{"BearerAuth":[]}],"x-vezoo-scope":"places","x-rate-limit-per-minute":20,"requestBody":{"required":true,"content":{"application\/json":{"schema":{"type":"object","required":["polyline"],"properties":{"polyline":{"type":"string","maxLength":500000},"categories":{"type":"array","maxItems":7,"uniqueItems":true,"items":{"$ref":"#\/components\/schemas\/PlaceCategory"}}},"example":{"polyline":"ENCODED_POLYLINE_FROM_ROUTE","categories":["fuel","food","lodging","parking","charging"]}}}}},"responses":{"200":{"description":"POIs grouped by category.","headers":{"X-API-Version":{"$ref":"#\/components\/headers\/ApiVersion"},"X-Request-Id":{"$ref":"#\/components\/headers\/RequestId"},"X-RateLimit-Limit":{"$ref":"#\/components\/headers\/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#\/components\/headers\/RateLimitRemaining"},"X-Quota-Limit":{"$ref":"#\/components\/headers\/QuotaLimit"},"X-Quota-Remaining":{"$ref":"#\/components\/headers\/QuotaRemaining"}},"content":{"application\/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"categories":{"type":"array","items":{"$ref":"#\/components\/schemas\/PlaceCategory"}},"counts":{"type":"object","additionalProperties":{"type":"integer"}},"places_by_category":{"type":"object","additionalProperties":{"type":"array","items":{"type":"object","additionalProperties":true}}}}}}}},"401":{"description":"Missing, invalid, disabled or expired API key.","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"403":{"description":"The key does not allow this scope or browser origin.","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"422":{"description":"Request validation failed.","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/ValidationError"}}}},"429":{"description":"Rate limit or total quota exceeded.","headers":{"Retry-After":{"$ref":"#\/components\/headers\/RetryAfter"},"X-API-Version":{"$ref":"#\/components\/headers\/ApiVersion"},"X-Request-Id":{"$ref":"#\/components\/headers\/RequestId"},"X-RateLimit-Limit":{"$ref":"#\/components\/headers\/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#\/components\/headers\/RateLimitRemaining"},"X-Quota-Limit":{"$ref":"#\/components\/headers\/QuotaLimit"},"X-Quota-Remaining":{"$ref":"#\/components\/headers\/QuotaRemaining"}},"content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"503":{"description":"Public API or a required routing service is temporarily unavailable.","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}}}}},"\/trip-insights":{"post":{"tags":["Trip data"],"summary":"Get route stop suggestions and smart trip plan","description":"Pass route.polyline returned by \/route. Smart plans are returned for sufficiently long routes when enabled.","operationId":"tripInsights","security":[{"BearerAuth":[]}],"x-vezoo-scope":"insights","x-rate-limit-per-minute":12,"requestBody":{"required":true,"content":{"application\/json":{"schema":{"type":"object","required":["polyline"],"properties":{"polyline":{"type":"string","maxLength":500000}},"example":{"polyline":"ENCODED_POLYLINE_FROM_ROUTE"}}}}},"responses":{"200":{"description":"Counts, suggested stops and automatic stop plan.","headers":{"X-API-Version":{"$ref":"#\/components\/headers\/ApiVersion"},"X-Request-Id":{"$ref":"#\/components\/headers\/RequestId"},"X-RateLimit-Limit":{"$ref":"#\/components\/headers\/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#\/components\/headers\/RateLimitRemaining"},"X-Quota-Limit":{"$ref":"#\/components\/headers\/QuotaLimit"},"X-Quota-Remaining":{"$ref":"#\/components\/headers\/QuotaRemaining"}},"content":{"application\/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"counts":{"type":"object","additionalProperties":{"type":"integer"}},"suggestions":{"type":"array","items":{"type":"object","additionalProperties":true}},"smart_plan":{"type":"array","items":{"type":"object","additionalProperties":true}}}}}}},"401":{"description":"Missing, invalid, disabled or expired API key.","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"403":{"description":"The key does not allow this scope or browser origin.","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"422":{"description":"Request validation failed.","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/ValidationError"}}}},"429":{"description":"Rate limit or total quota exceeded.","headers":{"Retry-After":{"$ref":"#\/components\/headers\/RetryAfter"},"X-API-Version":{"$ref":"#\/components\/headers\/ApiVersion"},"X-Request-Id":{"$ref":"#\/components\/headers\/RequestId"},"X-RateLimit-Limit":{"$ref":"#\/components\/headers\/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#\/components\/headers\/RateLimitRemaining"},"X-Quota-Limit":{"$ref":"#\/components\/headers\/QuotaLimit"},"X-Quota-Remaining":{"$ref":"#\/components\/headers\/QuotaRemaining"}},"content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"503":{"description":"Public API or a required routing service is temporarily unavailable.","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}}}}}}}