openapi: 3.1.0
info:
title: Google Maps Directions API
description: >-
The Google Maps Directions API returns directions between locations using
HTTP requests. Directions may specify origins, destinations, and waypoints
as text strings (e.g., an address or place name), place IDs, or
latitude/longitude coordinates. The API supports driving, walking,
bicycling, and transit travel modes with real-time traffic awareness.
version: "1.0"
termsOfService: https://cloud.google.com/maps-platform/terms
contact:
name: Google Maps Platform Team
url: https://developers.google.com/maps/support
license:
name: Google Maps Platform Terms of Service
url: https://cloud.google.com/maps-platform/terms
x-logo:
url: https://developers.google.com/maps/images/maps-icon.svg
externalDocs:
description: Google Maps Directions API Documentation
url: https://developers.google.com/maps/documentation/directions/overview
servers:
- url: https://maps.googleapis.com/maps/api
description: Google Maps Directions API production server
security:
- apiKey: []
tags:
- name: Directions
description: Route computation between origin and destination
externalDocs:
description: Directions API reference
url: https://developers.google.com/maps/documentation/directions/get-directions
paths:
/directions/json:
get:
operationId: getDirections
summary: Get Directions Between Two or More Locations
description: >-
Calculates directions between an origin and a destination, optionally
via waypoints. Supports driving, walking, bicycling, and transit modes.
Returns one or more routes composed of legs and steps, including
distance, duration, polylines, and turn-by-turn instructions.
tags:
- Directions
parameters:
- name: origin
in: query
required: true
description: >-
The address, place ID (prefixed with place_id:), or
latitude/longitude coordinates of the starting point.
schema:
type: string
example: "Toronto, ON"
- name: destination
in: query
required: true
description: >-
The address, place ID (prefixed with place_id:), or
latitude/longitude coordinates of the ending point.
schema:
type: string
example: "Montreal, QC"
- name: mode
in: query
description: >-
The travel mode for calculating directions. Defaults to driving.
schema:
type: string
enum:
- driving
- walking
- bicycling
- transit
default: driving
example: driving
- name: waypoints
in: query
description: >-
An array of intermediate locations to include along the route,
specified as pipe-separated values. Prefix with optimize:true to
allow the Directions service to optimize the route by rearranging
waypoints in a more efficient order. Each waypoint can be an
address, place ID, or lat/lng pair.
schema:
type: string
example: "optimize:true|Barrie, ON|Kingston, ON"
- name: alternatives
in: query
description: >-
If set to true, instructs the Directions service to return more
than one route alternative when available.
schema:
type: boolean
default: false
example: true
- name: avoid
in: query
description: >-
Indicates that the calculated route(s) should avoid the indicated
features. Pipe-separated list of restrictions.
schema:
type: string
example: "tolls|highways|ferries"
- name: language
in: query
description: >-
The language code in which to return results, where available.
schema:
type: string
example: "en"
- name: units
in: query
description: >-
Specifies the unit system to use when displaying results.
schema:
type: string
enum:
- metric
- imperial
example: metric
- name: region
in: query
description: >-
The region code, specified as a ccTLD two-character value. Biases
results towards a particular region.
schema:
type: string
example: "us"
- name: arrival_time
in: query
description: >-
The desired arrival time for transit directions, specified as
seconds since midnight, January 1, 1970 UTC. Cannot be used
with departure_time.
schema:
type: integer
format: int64
example: 10
- name: departure_time
in: query
description: >-
The desired departure time, specified as seconds since midnight,
January 1, 1970 UTC. For transit mode this is required if
arrival_time is not specified. For driving mode with
traffic_model, use "now" or a future timestamp.
schema:
oneOf:
- type: integer
format: int64
- type: string
enum:
- "now"
example: example_value
- name: traffic_model
in: query
description: >-
The assumptions to use when calculating travel time in traffic.
Only applies when mode is driving and departure_time is specified.
schema:
type: string
enum:
- best_guess
- pessimistic
- optimistic
default: best_guess
example: best_guess
- name: transit_mode
in: query
description: >-
Specifies one or more preferred modes of transit as a
pipe-separated list. Only valid when mode is transit.
schema:
type: string
example: "bus|subway"
- name: transit_routing_preference
in: query
description: >-
Specifies preferences for transit routes. Only valid when
mode is transit.
schema:
type: string
enum:
- less_walking
- fewer_transfers
example: less_walking
- name: key
in: query
required: true
description: >-
Your application's API key.
schema:
type: string
example: example_value
responses:
"200":
description: Directions response
content:
application/json:
schema:
$ref: "#/components/schemas/DirectionsResponse"
examples:
Getdirections200Example:
summary: Default getDirections 200 response
x-microcks-default: true
value:
status: OK
routes:
- summary: example_value
legs: {}
waypoint_order: {}
copyrights: example_value
warnings: {}
geocoded_waypoints:
- geocoder_status: OK
place_id: '500123'
types: {}
partial_match: true
error_message: example_value
"400":
description: Bad request - invalid parameters
"403":
description: Forbidden - API key is invalid or not authorized
"429":
description: Too many requests - rate limit exceeded
"500":
description: Internal server error
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
components:
securitySchemes:
apiKey:
type: apiKey
name: key
in: query
description: Google Maps Platform API key
schemas:
DirectionsResponse:
type: object
description: The response from the Directions API
properties:
status:
type: string
description: Status code of the directions request
enum:
- OK
- NOT_FOUND
- ZERO_RESULTS
- MAX_WAYPOINTS_EXCEEDED
- INVALID_REQUEST
- OVER_DAILY_LIMIT
- OVER_QUERY_LIMIT
- REQUEST_DENIED
- UNKNOWN_ERROR
example: OK
routes:
type: array
description: >-
Array of routes from the origin to the destination. Each
route contains legs, overview polylines, warnings, and
waypoint order.
items:
$ref: "#/components/schemas/Route"
example: []
geocoded_waypoints:
type: array
description: >-
Contains geocoding information for the origin, destination,
and each waypoint.
items:
$ref: "#/components/schemas/GeocodedWaypoint"
example: []
error_message:
type: string
description: Human-readable error message when status is not OK
example: example_value
required:
- status
- routes
Route:
type: object
description: >-
A single route containing a set of legs from the origin to the
destination with any specified waypoints.
properties:
summary:
type: string
description: >-
A short textual description for the route, suitable for
naming and disambiguating the route from alternatives.
example: "I-93 N"
legs:
type: array
description: >-
Array of route legs, one for each segment between waypoints.
A route with no waypoints will contain one leg.
items:
$ref: "#/components/schemas/Leg"
example: []
waypoint_order:
type: array
description: >-
An array indicating the order of any waypoints in the
calculated route. Waypoints may be reordered if the
request was passed optimize:true.
items:
type: integer
example: []
overview_polyline:
$ref: "#/components/schemas/Polyline"
bounds:
$ref: "#/components/schemas/Bounds"
copyrights:
type: string
description: Copyright text for display
example: "Map data ©2026 Google"
warnings:
type: array
description: Warnings to be displayed when showing the route
items:
type: string
example: []
fare:
$ref: "#/components/schemas/Fare"
required:
- summary
- legs
- overview_polyline
- bounds
- copyrights
Leg:
type: object
description: >-
A leg of a route, representing the journey between two waypoints
or the origin/destination.
properties:
steps:
type: array
description: >-
Array of steps representing each instruction along the leg
items:
$ref: "#/components/schemas/Step"
example: []
distance:
$ref: "#/components/schemas/TextValuePair"
duration:
$ref: "#/components/schemas/TextValuePair"
duration_in_traffic:
$ref: "#/components/schemas/TextValuePair"
start_location:
$ref: "#/components/schemas/LatLng"
end_location:
$ref: "#/components/schemas/LatLng"
start_address:
type: string
description: The human-readable address of the leg's starting point
example: "Toronto, ON, Canada"
end_address:
type: string
description: The human-readable address of the leg's ending point
example: "Montreal, QC, Canada"
arrival_time:
$ref: "#/components/schemas/TimeZoneTextValue"
departure_time:
$ref: "#/components/schemas/TimeZoneTextValue"
required:
- steps
- distance
- duration
- start_location
- end_location
- start_address
- end_address
Step:
type: object
description: A single step of a route leg
properties:
html_instructions:
type: string
description: >-
Formatted instructions for this step, presented as an HTML
text string.
example: "Head <b>north</b> on <b>Yonge St</b> toward <b>Queen St W</b>"
distance:
$ref: "#/components/schemas/TextValuePair"
duration:
$ref: "#/components/schemas/TextValuePair"
start_location:
$ref: "#/components/schemas/LatLng"
end_location:
$ref: "#/components/schemas/LatLng"
polyline:
$ref: "#/components/schemas/Polyline"
travel_mode:
type: string
description: The travel mode for this step
enum:
- DRIVING
- WALKING
- BICYCLING
- TRANSIT
example: DRIVING
maneuver:
type: string
description: >-
The maneuver action for this step (e.g., turn-left,
roundabout-right, merge, straight, etc.).
example: "turn-left"
transit_details:
$ref: "#/components/schemas/TransitDetails"
steps:
type: array
description: >-
Sub-steps for walking or transit legs in multi-modal routes
items:
$ref: "#/components/schemas/Step"
example: []
required:
- html_instructions
- distance
- duration
- start_location
- end_location
- polyline
- travel_mode
TransitDetails:
type: object
description: Transit-specific information for transit steps
properties:
arrival_stop:
$ref: "#/components/schemas/TransitStop"
departure_stop:
$ref: "#/components/schemas/TransitStop"
arrival_time:
$ref: "#/components/schemas/TimeZoneTextValue"
departure_time:
$ref: "#/components/schemas/TimeZoneTextValue"
headsign:
type: string
description: The direction in which to travel on this transit line
example: example_value
headway:
type: integer
description: >-
The expected number of seconds between departures from the
same stop at the current time
example: 10
num_stops:
type: integer
description: The number of stops from departure to arrival
example: 10
line:
$ref: "#/components/schemas/TransitLine"
TransitStop:
type: object
description: A transit stop
properties:
name:
type: string
description: The name of the transit stop
example: Example Title
location:
$ref: "#/components/schemas/LatLng"
TransitLine:
type: object
description: Information about a transit line
properties:
name:
type: string
description: The full name of this transit line
example: Example Title
short_name:
type: string
description: The short name of this transit line
example: example_value
color:
type: string
description: The color commonly used in signage for this line
example: example_value
text_color:
type: string
description: The color of the text commonly used for this line
example: example_value
vehicle:
type: object
properties:
name:
type: string
type:
type: string
icon:
type: string
format: uri
example: example_value
agencies:
type: array
items:
type: object
properties:
name:
type: string
url:
type: string
format: uri
phone:
type: string
example: []
TextValuePair:
type: object
description: >-
A text and numeric value pair used for distance, duration, and
fare amounts
properties:
text:
type: string
description: Human-readable text representation
example: "541 km"
value:
type: number
description: >-
Numeric value. For distance, expressed in meters. For
duration, expressed in seconds. For fare, expressed in
the currency indicated.
example: 541000
required:
- text
- value
TimeZoneTextValue:
type: object
description: A time value with text representation and time zone
properties:
text:
type: string
description: Human-readable time string
example: example_value
value:
type: integer
format: int64
description: Time expressed in seconds since epoch
example: 10
time_zone:
type: string
description: The time zone of this time value
example: "America/New_York"
Polyline:
type: object
description: An encoded polyline representation of a route or step
properties:
points:
type: string
description: >-
An encoded polyline string using the Encoded Polyline
Algorithm. Decode to obtain a series of lat/lng coordinates.
example: example_value
required:
- points
Fare:
type: object
description: The total fare for a transit route
properties:
currency:
type: string
description: ISO 4217 currency code
example: "USD"
value:
type: number
description: The total fare amount in the specified currency
example: 6.50
text:
type: string
description: Human-readable fare text
example: "$6.50"
required:
- currency
- value
- text
GeocodedWaypoint:
type: object
description: Geocoded information for a waypoint
properties:
geocoder_status:
type: string
description: Status of the geocoding operation
enum:
- OK
- ZERO_RESULTS
example: OK
place_id:
type: string
description: Place ID of the geocoded waypoint
example: '500123'
types:
type: array
description: Address type(s) of the geocoded waypoint
items:
type: string
example: []
partial_match:
type: boolean
description: Whether the geocoder did not return an exact match
example: true
LatLng:
type: object
description: A latitude/longitude coordinate pair
properties:
lat:
type: number
format: double
description: Latitude in decimal degrees
example: 42.5
lng:
type: number
format: double
description: Longitude in decimal degrees
example: 42.5
required:
- lat
- lng
Bounds:
type: object
description: A bounding box defined by northeast and southwest corners
properties:
northeast:
$ref: "#/components/schemas/LatLng"
southwest:
$ref: "#/components/schemas/LatLng"
required:
- northeast
- southwest