openapi: 3.0.0 info: title: Google Maps Directions Search Along Route API version: 1.0.0 description: | The Google Maps Directions Search Along Route API returns the places Google Maps surfaces along a driving route — for example gas stations, restaurants, coffee shops, or hotels between an origin and a destination. Results are distributed across the whole route corridor (not just near the origin), and each place includes its title, place ID, data ID, rating, reviews, address, phone, opening hours, and GPS coordinates. The route comes from the Google Maps Directions API (`google_maps_directions` engine): call it with your origin and destination, then pass the `search_along_route_token` it returns here as the `search_along_route_token` parameter, along with the place category in `q`. servers: - url: https://www.searchapi.io/api/v1 paths: /search: get: summary: Google Maps Directions Search Along Route security: - ApiKeyAuth: [] - ApiKeyQuery: [] parameters: - $ref: '#/components/parameters/engine' - $ref: '#/components/parameters/api_key' - $ref: '#/components/parameters/q' - $ref: '#/components/parameters/search_along_route_token' - $ref: '#/components/parameters/hl' - $ref: '#/components/parameters/page' responses: '200': description: Successful operation 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 parameters: q: name: q in: query required: true description: "Parameter defines the query to search for along the route, such as a category of places (e.g. Gas, Restaurants, Coffee, Hotels)." schema: type: string search_along_route_token: name: search_along_route_token in: query required: true description: "An opaque token returned in a google_maps_directions response that encodes the resolved route. Call google_maps_directions with the origin and destination first, then pass its search_along_route_token here." schema: type: string hl: name: hl in: query required: false description: "The default parameter en defines the interface language of the search. Check the full list of supported Google hl languages." 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"] page: name: page in: query required: false description: "Parameter defines which page of results to return. Each page holds up to 20 places along the route. By default, it is set to 1. Keep paging until the results run out." schema: type: integer minimum: 1 default: 1 engine: name: engine in: query required: true description: "Parameter defines an engine that will be used to retrieve real-time data. It must be set to google_maps_directions_search_along_route." schema: type: string enum: ["google_maps_directions_search_along_route"] api_key: name: api_key in: query required: true description: "The api_key authenticates your requests. Use it as a query parameter (https://www.searchapi.io/api/v1/search?api_key=YOUR_API_KEY) or in the Authorization header (Bearer YOUR_API_KEY)." schema: type: string schemas: SearchResponse: type: object properties: search_metadata: $ref: '#/components/schemas/SearchMetadata' search_parameters: $ref: '#/components/schemas/SearchParameters' search_information: $ref: '#/components/schemas/SearchInformation' error: type: string description: "Error message returned (at HTTP 200) when no results were found along the route" ads: type: array items: $ref: '#/components/schemas/MapAd' description: "Sponsored results" local_results: type: array items: $ref: '#/components/schemas/LocalResult' description: "Array of place/location results along the route" additionalProperties: false SearchMetadata: type: object 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 search" html_url: type: string description: "URL to view HTML results" json_url: type: string description: "URL to view JSON results" required: [id, status, created_at] SearchParameters: type: object properties: engine: type: string description: "Search engine used" q: type: string description: "Query searched along the route" search_along_route_token: type: string description: "Token encoding the resolved route, from a google_maps_directions response" hl: type: string description: "Interface language" page: type: integer description: "Page of results returned" SearchInformation: type: object properties: query_displayed: type: string description: "The query that was actually displayed/processed" did_you_mean: type: string description: "Alternative spelling suggestion if available" state: type: string description: "Information about the spelling state" enum: ["Showing results for fixed spelling.", "Showing results for exact spelling.", "Showing results for original spelling."] additionalProperties: false ErrorResponse: type: object required: [error] properties: error: type: string description: Error message describing what went wrong MapAd: allOf: - $ref: '#/components/schemas/LocalResult' - type: object properties: tracking_title: type: string description: "Tracking title for ad" tracking_link: type: string description: "Tracking link for ad" LocalResult: type: object properties: position: type: integer description: "Position in search results" ludocid: type: string description: "Local unique document identifier" place_id: type: string description: "Google Place ID" kgmid: type: string description: "Knowledge Graph machine identifier" data_id: type: string description: "Data identifier" title: type: string description: "Place name" description: type: string description: "Place description" features: type: array items: type: string description: "List of features" address: type: string description: "Physical address" city: type: string description: "City (and region/country) label of the place" country_code: type: string description: "Two-letter country code of the place" timezone: type: string description: "Time zone of the place" detour: type: object description: "Off-route deviation required to reach this place from the route" properties: duration: type: integer description: "Extra driving time in seconds" formatted_duration: type: string description: "Localized extra driving time (e.g. \"4 min\")" distance: type: integer description: "Extra distance in meters" formatted_distance: type: string description: "Localized extra distance (e.g. \"0.8 mi\" or \"1,3 km\")" fuel_price: type: string description: "Per-unit fuel price for gas stations (e.g. \"$5.80/Regular\")" phone: type: string description: "Phone number" price: type: string description: "Price level or cost information" price_description: type: string description: "Description of pricing" hotel_stars: type: integer description: "Hotel star rating" rating: type: number description: "Average rating" reviews: type: integer description: "Number of reviews" reviews_link: type: string description: "Link to reviews" review_text: type: string description: "Sample review text" is_unclaimed_listing: type: boolean description: "Whether this is an unclaimed business listing" website: type: string description: "Business website URL" domain: type: string description: "Website domain" gps_coordinates: type: object properties: latitude: type: number description: "Latitude coordinate" longitude: type: number description: "Longitude coordinate" description: "GPS coordinates of the place" type: type: string description: "Primary place type or category" types: type: array items: type: string description: "Array of place types/categories" tracking_title: type: string description: "Tracking title (for ads)" tracking_link: type: string description: "Tracking link (for ads)" posts: type: array items: type: object properties: title: type: string description: "Post title" source: type: string description: "Post source" link: type: string description: "Post link" additionalProperties: false description: "Related posts" amenities: type: array items: type: string description: "Available amenities" highlights: type: array items: type: string description: "Highlight attribute chips (e.g. LGBTQ+ friendly, Women-owned)" open_state: type: string description: "Current operating status" hours: type: string description: "Operating hours information" open_hours: type: object additionalProperties: type: string description: "Detailed opening hours by day" reservation: type: object description: "Primary reservation/booking provider for the place" properties: link: type: string description: "Reservation URL" source: type: string description: "Reservation provider domain" reservation_links: type: array items: type: object properties: text: type: string description: "Link text" link: type: string description: "Reservation URL" additionalProperties: false description: "Reservation booking links" extensions: type: array items: type: object properties: title: type: string description: "Extension category title" items: type: array items: type: object properties: title: type: string description: "Item title" value: type: string description: "Item value" additionalProperties: false additionalProperties: false description: "Additional place information extensions" images: type: array items: type: string description: "Array of image URLs" thumbnail: type: string description: "Place thumbnail image URL"