openapi: 3.0.0 info: title: Google Maps Directions API version: 1.0.0 description: | The Google Maps Directions API returns directions between locations as text within a set time frame. The API returns suggested routes, distances, and estimated travel times. **Cross-linking**: The `from` and `to` location fields returned by this API can be used with other Google Maps APIs to fetch detailed place information using the Google Maps Place API. The `coordinates` in `places_info` represent the location on a map. servers: - url: https://www.searchapi.io/api/v1 paths: /search: get: summary: Google Maps Directions Search description: Retrieve directions between two locations with multiple travel modes and routing options. operationId: googleMapsDirectionsSearch security: - ApiKeyAuth: [] - ApiKeyQuery: [] parameters: - name: engine in: query required: true description: 'Set to "google_maps_directions" to use the Google Maps Directions API' schema: type: string enum: ["google_maps_directions"] - name: api_key in: query required: true description: 'Your SearchAPI API key. Pass as query parameter: api_key=YOUR_API_KEY or as Authorization header: Bearer YOUR_API_KEY' schema: type: string - name: from in: query required: true description: 'Starting location. Can be a plain address, data ID, or coordinates (lat,long). (e.g., "New York", "0x89c25a27aeb46f51:0x92f0ae3e12b1bf58" or "40.7128,-74.0060")' schema: type: string - name: to in: query required: true description: 'Destination location. Can be a plain address, data ID, or coordinates (lat,long). (e.g., "Boston", "0x89c25a27aeb46f51:0x92f0ae3e12b1bf58" or "42.3601,-71.0589")' schema: type: string - name: waypoints in: query required: false description: 'A JSON array of intermediate points to visit between from and to. Can be a plain address, data ID, or coordinates (lat,long). Maximum 8 waypoints allowed. Transit mode does not support waypoints. Cannot be combined with the time parameter. Example: ["0x40d8a9890932b5d5:0x8b7c49e19a7fc6a4", "Times Square, New York"]' schema: type: string - name: travel_mode in: query required: false description: 'The mode of transportation to use when calculating directions. Defaults to "best" which automatically selects the most appropriate mode.' schema: type: string enum: ["best", "driving", "cycling", "walking", "transit", "flying"] default: "best" - name: time in: query required: false description: 'Specifies the time to use for traffic-aware routing. Format: "depart_at:" for departure time, "arrive_by:" for arrival time, or "last_available" for transit mode to get the latest available route. Only available with travel_mode=transit for time-aware routes.' schema: type: string - name: route in: query required: false description: 'Routing preference for transit mode. Only supported when travel_mode is "transit".' schema: type: string enum: ["best", "fewer_transfers", "less_walking", "wheelchair_accessible"] default: "best" - name: prefer in: query required: false description: 'A JSON array of transit preferences. Only supported when travel_mode is "transit". Example: ["bus", "subway"]' schema: type: string - name: avoid in: query required: false description: 'A JSON array of features to avoid. For driving/best mode: ["tolls", "highways", "ferries"]. For walking/cycling: only ["ferries"] is supported. Not supported for transit/flying. Example: ["tolls", "highways"]' schema: type: string - name: distance_units in: query required: false description: 'Units for distance values in the response. Not supported for transit or flying modes.' schema: type: string enum: ["automatic", "km", "mi"] default: "automatic" - name: gl in: query required: false description: 'The country code of the location to use for the search. Defaults to "us". Accepts standard ISO 3166-1 alpha-2 country codes.' schema: type: string default: "us" enum: ["af", "al", "dz", "as", "ad", "ao", "ai", "aq", "ag", "ar", "am", "aw", "au", "at", "az", "bs", "bh", "bd", "bb", "by", "be", "bz", "bj", "bm", "bt", "bo", "ba", "bw", "bv", "br", "io", "bn", "bg", "bf", "bi", "kh", "cm", "ca", "cv", "ky", "cf", "td", "cl", "cn", "cx", "cc", "co", "km", "cg", "cd", "ck", "cr", "ci", "hr", "cu", "cy", "cz", "dk", "dj", "dm", "do", "ec", "eg", "sv", "gq", "er", "ee", "et", "fk", "fo", "fj", "fi", "fr", "gf", "pf", "tf", "ga", "gm", "ge", "de", "gh", "gi", "gr", "gl", "gd", "gp", "gu", "gt", "gn", "gw", "gy", "ht", "hm", "va", "hn", "hk", "hu", "is", "in", "id", "ir", "iq", "ie", "il", "it", "jm", "jp", "jo", "kz", "ke", "ki", "kp", "kr", "kw", "kg", "la", "lv", "lb", "ls", "lr", "ly", "li", "lt", "lu", "mo", "mk", "mg", "mw", "my", "mv", "ml", "mt", "mh", "mq", "mr", "mu", "yt", "mx", "fm", "md", "mc", "mn", "ms", "ma", "mz", "mm", "na", "nr", "np", "nl", "nc", "nz", "ni", "ne", "ng", "nu", "nf", "mp", "no", "om", "pk", "pw", "ps", "pa", "pg", "py", "pe", "ph", "pn", "pl", "pt", "pr", "qa", "re", "ro", "ru", "rw", "sh", "kn", "lc", "pm", "vc", "ws", "sm", "st", "sa", "sn", "rs", "sc", "sl", "sg", "sk", "si", "sb", "so", "za", "gs", "es", "lk", "sd", "sr", "sj", "sz", "se", "ch", "sy", "tw", "tj", "tz", "th", "tl", "tg", "tk", "to", "tt", "tn", "tr", "tm", "tc", "tv", "ug", "ua", "ae", "uk", "gb", "us", "um", "uy", "uz", "vu", "ve", "vn", "vg", "vi", "wf", "eh", "ye", "zm", "zw", "gg", "je", "im", "me"] - name: hl in: query required: false description: 'The language to use for the search results. Defaults to "en" (English). Accepts standard language codes.' schema: type: string default: "en" enum: ["af", "ak", "sq", "am", "ar", "hy", "az", "eu", "be", "bem", "bn", "bh", "xx-bork", "bs", "br", "bg", "km", "ca", "chr", "ny", "zh-cn", "zh-tw", "co", "hr", "cs", "da", "nl", "xx-elmer", "en", "eo", "et", "ee", "fo", "tl", "fi", "fr", "fy", "gaa", "gl", "ka", "de", "el", "kl", "gn", "gu", "xx-hacker", "ht", "ha", "haw", "iw", "hi", "hu", "is", "ig", "id", "ia", "ga", "it", "ja", "jw", "kn", "kk", "rw", "rn", "xx-klingon", "kg", "ko", "kri", "ku", "ckb", "ky", "lo", "la", "lv", "ln", "lt", "loz", "lg", "ach", "mk", "mg", "my", "ms", "ml", "mt", "mv", "mi", "mr", "mfe", "mo", "mn", "sr-me", "ne", "pcm", "nso", "no", "nn", "oc", "or", "om", "ps", "fa", "xx-pirate", "pl", "pt", "pt-br", "pt-pt", "pa", "qu", "ro", "rm", "nyn", "ru", "gd", "sr", "sh", "st", "tn", "crs", "sn", "sd", "si", "sk", "sl", "so", "es", "es-419", "su", "sw", "sv", "tg", "ta", "tt", "te", "th", "ti", "to", "lua", "tum", "tr", "tk", "tw", "ug", "uk", "ur", "uz", "vu", "vi", "cy", "wo", "xh", "yi", "yo", "zu"] responses: '200': description: Successful response containing directions and place information content: application/json: schema: $ref: '#/components/schemas/SearchResponse' '400': description: 'Validation Error. There is an issue with query parameters, such as missing required parameters or invalid values.' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': description: 'Authentication Error. The API key is missing or invalid.' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '429': description: 'Rate Limit Exceeded. The number of allowed requests has been exceeded. Consider upgrading your plan or waiting for the limit to reset.' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: 'Server Error. Internal server error.' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '503': description: 'Timeout. We could not retrieve results in 90 seconds.' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' components: securitySchemes: ApiKeyAuth: type: apiKey in: header name: Authorization description: 'Use Bearer authentication. Format: "Bearer YOUR_API_KEY"' ApiKeyQuery: type: apiKey in: query name: api_key description: Pass API key as query parameter schemas: SearchResponse: type: object properties: search_metadata: $ref: '#/components/schemas/SearchMetadata' search_parameters: $ref: '#/components/schemas/SearchParameters' error: type: string description: Error message if no results were found travel_modes: type: array description: Available travel modes with their durations items: $ref: '#/components/schemas/TravelMode' places_info: type: array description: Information about the starting and ending locations items: $ref: '#/components/schemas/PlaceInfo' directions: type: array description: Detailed directions for the route items: $ref: '#/components/schemas/Direction' SearchMetadata: type: object required: [id, status, created_at] properties: id: type: string description: Unique identifier for the search request status: type: string description: Status of the search request created_at: type: string format: date-time description: Timestamp when the search was created request_time_taken: type: number description: Time taken to make the request in seconds parsing_time_taken: type: number description: Time taken to parse the results in seconds total_time_taken: type: number description: Total time taken for the search in seconds request_url: type: string description: Google Maps URL for this directions search html_url: type: string description: URL to view HTML results json_url: type: string description: URL to view JSON results SearchParameters: type: object properties: engine: type: string description: The search engine used from: type: string description: The starting location to: type: string description: The destination location waypoints: type: string description: Intermediate waypoints (JSON array) travel_mode: type: string description: The selected travel mode time: type: string description: The time parameter if specified route: type: string description: The routing preference for transit prefer: type: string description: Transit preferences (JSON array) avoid: type: string description: Features to avoid (JSON array) distance_units: type: string description: The distance units selected gl: type: string description: Country code used for the search hl: type: string description: Language used for the search TravelMode: type: object properties: travel_mode: type: string description: 'The travel mode (Best, Driving, Cycling, Walking, Transit, or Flying)' formatted_duration: type: string description: Human-readable duration for this travel mode duration: type: integer description: Duration in seconds for this travel mode PlaceInfo: type: object properties: address: type: string description: The address of the location data_id: type: string description: Google Maps Place ID for this location coordinates: $ref: '#/components/schemas/Coordinates' Coordinates: type: object properties: latitude: type: number format: float description: Latitude coordinate longitude: type: number format: float description: Longitude coordinate Direction: type: object properties: travel_mode: type: string description: The travel mode for this direction (e.g., Driving, Transit, Walking, Cycling, Flying) distance: type: integer description: Distance in meters duration: type: integer description: Duration in seconds formatted_distance: type: string description: Human-readable distance formatted_duration: type: string description: Human-readable duration via: type: string description: Additional routing information (optional) formatted_typical_duration: type: string description: Typical duration under normal traffic conditions (driving mode) optimistic_duration: type: integer description: Best case scenario duration in seconds (driving mode) pessimistic_duration: type: integer description: Worst case scenario duration in seconds (driving mode) warnings: type: array items: type: string description: Any warnings for this route (e.g., tolls, ferries, unpaved roads) frequency: type: string description: Service frequency information (transit mode) time_window: $ref: '#/components/schemas/TimeWindow' buy_ticket: $ref: '#/components/schemas/BuyTicket' departure: type: string description: Departure information (flying mode) arrival: type: string description: Arrival information (flying mode) formatted_price: type: string description: Formatted flight price (flying mode) price: type: integer description: Flight price in cents (flying mode) airlines: type: string description: Airlines for the flight (flying mode) flights_link: type: string description: Link to book flights (flying mode) instructions: type: array items: $ref: '#/components/schemas/Instruction' description: Step-by-step instructions for this direction TimeWindow: type: object properties: depart_at: type: string description: Departure time depart_at_tz: type: string description: Departure timezone arrive_at: type: string description: Arrival time arrive_at_tz: type: string description: Arrival timezone BuyTicket: type: object properties: title: type: string description: Title of the ticket option price: type: string description: Price of the ticket offers: type: array items: $ref: '#/components/schemas/TicketOffer' description: Available ticket offers TicketOffer: type: object properties: source: type: string description: Name of the ticket vendor price: type: string description: Price from this vendor easy_checkout: type: boolean description: Whether easy checkout is available link: type: string description: Link to purchase the ticket favicon: type: string description: Favicon URL for the vendor Instruction: type: object properties: travel_mode: type: string description: Travel mode for this instruction step action: type: string description: The action to take (e.g., "Head north", "Turn right") information: type: string description: Additional information about this instruction formatted_duration: type: string description: Duration for this instruction formatted_distance: type: string description: Distance for this instruction duration: type: integer description: Duration in seconds distance: type: integer description: Distance in meters latitude: type: number format: float description: Latitude of the instruction location longitude: type: number format: float description: Longitude of the instruction location street_view: type: string description: Street view image URL for this location depart_from: $ref: '#/components/schemas/Location' direction: type: string description: Direction of transit travel (transit mode) vehicle: type: string description: Vehicle type (transit mode) line_name: type: string description: Transit line name (transit mode) line_number: type: string description: Transit line number (transit mode) arrive_at: $ref: '#/components/schemas/Location' service_provider: $ref: '#/components/schemas/ServiceProvider' stops: type: array items: $ref: '#/components/schemas/Location' description: Intermediate stops (transit mode) details: type: array items: $ref: '#/components/schemas/Instruction' description: Detailed sub-instructions Location: type: object properties: place: type: string description: Name of the location at: type: string description: Time information for this location platform: type: string description: Platform information (transit mode) timezone: type: string description: Timezone of the location latitude: type: number format: float description: Latitude coordinate longitude: type: number format: float description: Longitude coordinate data_id: type: string description: Google Maps Place ID for this location ServiceProvider: type: object properties: name: type: string description: Name of the service provider contact: type: string description: Contact information for the service provider website: type: string description: Website URL for the service provider ErrorResponse: type: object required: [error] properties: error: type: string description: Error message describing what went wrong