Google Maps Platform Autocomplete API

openapi: 3.1.0
info:
  title: Google Maps Directions Autocomplete 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
servers:
- url: https://maps.googleapis.com/maps/api
  description: Google Maps Directions API production server
security:
- apiKey: []
tags:
- name: Autocomplete
  description: Get place predictions based on text input
paths:
  /places:autocomplete:
    post:
      operationId: autocompletePlaces
      summary: Get Place Autocomplete Predictions
      description: Returns predictions for the given input text. Predictions include place predictions and query predictions. Use session tokens to group autocomplete requests for billing purposes.
      tags:
      - Autocomplete
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AutocompleteRequest'
            examples:
              AutocompleteplacesRequestExample:
                summary: Default autocompletePlaces request
                x-microcks-default: true
                value:
                  input: example_value
                  locationBias: {}
                  locationRestriction: {}
                  includedPrimaryTypes:
                  - example_value
                  includedRegionCodes:
                  - example_value
                  languageCode: example_value
                  regionCode: example_value
                  origin:
                    latitude: 42.5
                    longitude: 42.5
                  inputOffset: 10
                  includeQueryPredictions: true
                  sessionToken: example_value
      responses:
        '200':
          description: Autocomplete response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AutocompleteResponse'
              examples:
                Autocompleteplaces200Example:
                  summary: Default autocompletePlaces 200 response
                  x-microcks-default: true
                  value:
                    suggestions:
                    - {}
        '400':
          description: Bad request
        '403':
          description: Forbidden
        '429':
          description: Too many requests
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  schemas:
    LatLng:
      type: object
      description: A latitude/longitude coordinate pair
      properties:
        latitude:
          type: number
          format: double
          description: Latitude in decimal degrees
          example: -33.8688
        longitude:
          type: number
          format: double
          description: Longitude in decimal degrees
          example: 151.2093
      required:
      - latitude
      - longitude
    StructuredFormat:
      type: object
      description: Contains the main text and secondary text of a prediction
      properties:
        mainText:
          $ref: '#/components/schemas/FormattableText'
        secondaryText:
          $ref: '#/components/schemas/FormattableText'
    FormattableText:
      type: object
      description: Text with structured formatting information
      properties:
        text:
          type: string
          description: The full text string
          example: example_value
        matches:
          type: array
          description: List of string ranges identifying where the input request matched in the text
          items:
            type: object
            properties:
              startOffset:
                type: integer
              endOffset:
                type: integer
          example: []
    AutocompleteRequest:
      type: object
      description: Request body for place autocomplete predictions
      properties:
        input:
          type: string
          description: The text input specifying which place to search for
          example: pizza near
        locationBias:
          $ref: '#/components/schemas/LocationBias'
        locationRestriction:
          $ref: '#/components/schemas/LocationRestriction'
        includedPrimaryTypes:
          type: array
          description: Restrict results to primary types
          items:
            type: string
          example: []
        includedRegionCodes:
          type: array
          description: Restrict results to these region codes
          items:
            type: string
          example: []
        languageCode:
          type: string
          description: The language code for predictions
          example: example_value
        regionCode:
          type: string
          description: Region code for biasing
          example: example_value
        origin:
          $ref: '#/components/schemas/LatLng'
        inputOffset:
          type: integer
          description: Zero-based Unicode character offset of input indicating the cursor position. Use to return more relevant predictions.
          example: 10
        includeQueryPredictions:
          type: boolean
          description: Whether to include query predictions in results
          example: true
        sessionToken:
          type: string
          description: A random string that groups this request with subsequent Place Details requests for billing.
          example: example_value
      required:
      - input
    AutocompleteResponse:
      type: object
      description: Response from the autocomplete endpoint
      properties:
        suggestions:
          type: array
          description: List of autocomplete suggestions
          items:
            $ref: '#/components/schemas/Suggestion'
          example: []
    Suggestion:
      type: object
      description: A single autocomplete suggestion
      properties:
        placePrediction:
          $ref: '#/components/schemas/PlacePrediction'
        queryPrediction:
          $ref: '#/components/schemas/QueryPrediction'
    Circle:
      type: object
      description: A circle defined by center point and radius
      properties:
        center:
          $ref: '#/components/schemas/LatLng'
        radius:
          type: number
          format: double
          description: The radius of the circle in meters
          example: 500.0
      required:
      - center
      - radius
    Rectangle:
      type: object
      description: A rectangular area defined by two corners
      properties:
        low:
          $ref: '#/components/schemas/LatLng'
        high:
          $ref: '#/components/schemas/LatLng'
      required:
      - low
      - high
    LocationBias:
      type: object
      description: The region to bias results to. Results in the specified region are ranked higher but results outside the region may still be returned.
      properties:
        circle:
          $ref: '#/components/schemas/Circle'
        rectangle:
          $ref: '#/components/schemas/Rectangle'
    QueryPrediction:
      type: object
      description: A query prediction
      properties:
        text:
          $ref: '#/components/schemas/FormattableText'
        structuredFormat:
          $ref: '#/components/schemas/StructuredFormat'
    LocationRestriction:
      type: object
      description: The region to restrict results to. Only results inside the restriction are returned.
      properties:
        circle:
          $ref: '#/components/schemas/Circle'
        rectangle:
          $ref: '#/components/schemas/Rectangle'
    PlacePrediction:
      type: object
      description: A place prediction
      properties:
        place:
          type: string
          description: The resource name of the suggested place in the format places/{placeId}
          example: example_value
        placeId:
          type: string
          description: The place ID of the suggested place
          example: '500123'
        text:
          $ref: '#/components/schemas/FormattableText'
        structuredFormat:
          $ref: '#/components/schemas/StructuredFormat'
        types:
          type: array
          description: List of types that apply to this place
          items:
            type: string
          example: []
        distanceMeters:
          type: integer
          description: The distance in meters from the origin
          example: 10
  securitySchemes:
    apiKey:
      type: apiKey
      name: key
      in: query
      description: Google Maps Platform API key
externalDocs:
  description: Google Maps Directions API Documentation
  url: https://developers.google.com/maps/documentation/directions/overview