Places API (New)

openapi: 3.1.0
info:
  title: Google Maps Places API (New)
  description: >-
    The Places API (New) lets you search for place information using HTTP
    requests. It provides endpoints for text search, nearby search, place
    details, autocomplete, and place photos. The API returns comprehensive
    place data including names, addresses, types, ratings, reviews, opening
    hours, and photos. This is the next-generation Places API built on
    Google's latest infrastructure.
  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 Places API (New) Documentation
  url: https://developers.google.com/maps/documentation/places/web-service/op-overview

servers:
- url: https://places.googleapis.com/v1
  description: Google Maps Places API (New) production server

security:
- apiKey: []

tags:
- name: Place Details
  description: Get detailed information about a specific place
- name: Text Search
  description: Search for places using a text query
- name: Nearby Search
  description: Search for places near a specific location
- name: Autocomplete
  description: Get place predictions based on text input
- name: Photos
  description: Access photos associated with places

paths:
  /places/{placeId}:
    get:
      operationId: getPlaceDetails
      summary: Get Details About a Place
      description: >-
        Returns detailed information about a place identified by its resource
        name. Use the fieldMask parameter to specify which fields to return.
        Only fields specified in the field mask are returned; requesting
        fewer fields reduces cost and improves performance.
      tags:
      - Place Details
      parameters:
      - name: placeId
        in: path
        required: true
        description: >-
          The resource name of a place in the format places/{placeId}.
        schema:
          type: string
        example: "ChIJN1t_tDeuEmsRUsoyG83frY4"
      - $ref: "#/components/parameters/fieldMask"
      - $ref: "#/components/parameters/languageCode"
      - $ref: "#/components/parameters/regionCode"
      - $ref: "#/components/parameters/sessionToken"
      responses:
        "200":
          description: Place details response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Place"
              examples:
                Getplacedetails200Example:
                  summary: Default getPlaceDetails 200 response
                  x-microcks-default: true
                  value:
                    name: Example Title
                    id: abc123
                    displayName:
                      text: example_value
                      languageCode: example_value
                    types:
                    - example_value
                    primaryType: example_value
                    primaryTypeDisplayName:
                      text: example_value
                      languageCode: example_value
                    nationalPhoneNumber: example_value
                    internationalPhoneNumber: example_value
                    formattedAddress: example_value
                    shortFormattedAddress: example_value
                    addressComponents:
                    - longText: example_value
                      shortText: example_value
                      types: {}
                      languageCode: example_value
                    location:
                      latitude: 42.5
                      longitude: 42.5
                    viewport: {}
                    rating: 42.5
                    userRatingCount: 10
                    googleMapsUri: https://www.example.com
                    websiteUri: https://www.example.com
                    regularOpeningHours:
                      openNow: true
                      periods:
                      - {}
                      weekdayDescriptions:
                      - {}
                    currentOpeningHours:
                      openNow: true
                      periods:
                      - {}
                      weekdayDescriptions:
                      - {}
                    priceLevel: PRICE_LEVEL_UNSPECIFIED
                    businessStatus: BUSINESS_STATUS_UNSPECIFIED
                    utcOffsetMinutes: 10
                    reviews:
                    - name: Example Title
                      relativePublishTimeDescription: example_value
                      rating: 42.5
                      publishTime: '2026-01-15T10:30:00Z'
                    photos:
                    - name: Example Title
                      widthPx: 10
                      heightPx: 10
                      authorAttributions: {}
                    editorialSummary:
                      text: example_value
                      languageCode: example_value
                    adrFormatAddress: example_value
                    iconMaskBaseUri: https://www.example.com
                    iconBackgroundColor: example_value
                    plusCode:
                      globalCode: example_value
                      compoundCode: example_value
                    accessibilityOptions:
                      wheelchairAccessibleParking: true
                      wheelchairAccessibleEntrance: true
                      wheelchairAccessibleRestroom: true
                      wheelchairAccessibleSeating: true
                    parkingOptions:
                      freeParkingLot: true
                      paidParkingLot: true
                      freeStreetParking: true
                      paidStreetParking: true
                      valetParking: true
                      freeGarageParking: true
                      paidGarageParking: true
                    paymentOptions:
                      acceptsCreditCards: true
                      acceptsDebitCards: true
                      acceptsCashOnly: true
                      acceptsNfc: true
                    dineIn: true
                    takeout: true
                    delivery: true
                    curbsidePickup: true
                    reservable: true
                    servesBreakfast: true
                    servesLunch: true
                    servesDinner: true
                    servesBeer: true
                    servesWine: true
                    servesVegetarianFood: true
        "400":
          description: Bad request
        "403":
          description: Forbidden
        "404":
          description: Place not found
        "429":
          description: Too many requests

      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /places:searchText:
    post:
      operationId: searchPlacesText
      summary: Search for Places Using a Text Query
      description: >-
        Returns a list of places matching a text query. You can use natural
        language queries such as "pizza in New York" or "shoe stores near
        Burlington". The service responds with a list of places matching
        the text string and any location bias or restriction that has been
        set. The service is especially useful for making ambiguous address
        queries in an automated system.
      tags:
      - Text Search
      parameters:
      - $ref: "#/components/parameters/fieldMask"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/SearchTextRequest"
            examples:
              SearchplacestextRequestExample:
                summary: Default searchPlacesText request
                x-microcks-default: true
                value:
                  textQuery: example_value
                  includedType: example_value
                  languageCode: example_value
                  regionCode: example_value
                  rankPreference: RELEVANCE
                  maxResultCount: 10
                  locationBias: {}
                  locationRestriction: {}
                  priceLevels:
                  - PRICE_LEVEL_INEXPENSIVE
                  openNow: true
                  minRating: 42.5
                  strictTypeFiltering: true
      responses:
        "200":
          description: Text search response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SearchPlacesResponse"
              examples:
                Searchplacestext200Example:
                  summary: Default searchPlacesText 200 response
                  x-microcks-default: true
                  value:
                    places:
                    - name: Example Title
                      id: abc123
                      types: {}
                      primaryType: example_value
                      nationalPhoneNumber: example_value
                      internationalPhoneNumber: example_value
                      formattedAddress: example_value
                      shortFormattedAddress: example_value
                      addressComponents: {}
                      rating: 42.5
                      userRatingCount: 10
                      googleMapsUri: https://www.example.com
                      websiteUri: https://www.example.com
                      priceLevel: PRICE_LEVEL_UNSPECIFIED
                      businessStatus: BUSINESS_STATUS_UNSPECIFIED
                      utcOffsetMinutes: 10
                      reviews: {}
                      photos: {}
                      adrFormatAddress: example_value
                      iconMaskBaseUri: https://www.example.com
                      iconBackgroundColor: example_value
                      dineIn: true
                      takeout: true
                      delivery: true
                      curbsidePickup: true
                      reservable: true
                      servesBreakfast: true
                      servesLunch: true
                      servesDinner: true
                      servesBeer: true
                      servesWine: true
                      servesVegetarianFood: true
                    nextPageToken: example_value
        "400":
          description: Bad request
        "403":
          description: Forbidden
        "429":
          description: Too many requests

      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /places:searchNearby:
    post:
      operationId: searchPlacesNearby
      summary: Search for Places Near a Location
      description: >-
        Returns a list of places near a specified location. You can refine
        results by specifying included types, excluded types, primary types,
        and ranking preferences. A location restriction (circle) is required.
      tags:
      - Nearby Search
      parameters:
      - $ref: "#/components/parameters/fieldMask"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/SearchNearbyRequest"
            examples:
              SearchplacesnearbyRequestExample:
                summary: Default searchPlacesNearby request
                x-microcks-default: true
                value:
                  includedTypes:
                  - example_value
                  excludedTypes:
                  - example_value
                  includedPrimaryTypes:
                  - example_value
                  excludedPrimaryTypes:
                  - example_value
                  languageCode: example_value
                  regionCode: example_value
                  rankPreference: POPULARITY
                  maxResultCount: 10
                  locationRestriction: {}
      responses:
        "200":
          description: Nearby search response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SearchPlacesResponse"
              examples:
                Searchplacesnearby200Example:
                  summary: Default searchPlacesNearby 200 response
                  x-microcks-default: true
                  value:
                    places:
                    - name: Example Title
                      id: abc123
                      types: {}
                      primaryType: example_value
                      nationalPhoneNumber: example_value
                      internationalPhoneNumber: example_value
                      formattedAddress: example_value
                      shortFormattedAddress: example_value
                      addressComponents: {}
                      rating: 42.5
                      userRatingCount: 10
                      googleMapsUri: https://www.example.com
                      websiteUri: https://www.example.com
                      priceLevel: PRICE_LEVEL_UNSPECIFIED
                      businessStatus: BUSINESS_STATUS_UNSPECIFIED
                      utcOffsetMinutes: 10
                      reviews: {}
                      photos: {}
                      adrFormatAddress: example_value
                      iconMaskBaseUri: https://www.example.com
                      iconBackgroundColor: example_value
                      dineIn: true
                      takeout: true
                      delivery: true
                      curbsidePickup: true
                      reservable: true
                      servesBreakfast: true
                      servesLunch: true
                      servesDinner: true
                      servesBeer: true
                      servesWine: true
                      servesVegetarianFood: true
                    nextPageToken: example_value
        "400":
          description: Bad request
        "403":
          description: Forbidden
        "429":
          description: Too many requests

      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /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
  /places/{placeId}/photos/{photoReference}/media:
    get:
      operationId: getPlacePhoto
      summary: Get a Place Photo
      description: >-
        Returns a photo for a place. After you get the photo resource name
        from a Place Details or Search response, use this endpoint to get
        the photo bytes. Specify maxHeightPx or maxWidthPx (or both) to
        control the image dimensions.
      tags:
      - Photos
      parameters:
      - name: placeId
        in: path
        required: true
        description: The place ID
        schema:
          type: string
        example: '500123'
      - name: photoReference
        in: path
        required: true
        description: The photo resource reference
        schema:
          type: string
        example: example_value
      - name: maxHeightPx
        in: query
        description: >-
          Maximum height of the image in pixels. Must be between 1 and
          4800. If maxHeightPx is set without maxWidthPx, the image is
          resized to the specified height, preserving aspect ratio.
        schema:
          type: integer
          minimum: 1
          maximum: 4800
        example: 10
      - name: maxWidthPx
        in: query
        description: >-
          Maximum width of the image in pixels. Must be between 1 and
          4800. If maxWidthPx is set without maxHeightPx, the image is
          resized to the specified width, preserving aspect ratio.
        schema:
          type: integer
          minimum: 1
          maximum: 4800
        example: 10
      - name: skipHttpRedirect
        in: query
        description: >-
          If set to true, skip the default HTTP redirect behavior and
          return a JSON response containing the photo URI.
        schema:
          type: boolean
          default: false
        example: true
      responses:
        "200":
          description: Photo media
          content:
            image/*:
              schema:
                type: string
                format: binary
              examples:
                Getplacephoto200Example:
                  summary: Default getPlacePhoto 200 response
                  x-microcks-default: true
                  value: example_value
            application/json:
              schema:
                $ref: "#/components/schemas/PhotoMedia"
              examples:
                Getplacephoto200Example:
                  summary: Default getPlacePhoto 200 response
                  x-microcks-default: true
                  value:
                    name: Example Title
                    photoUri: https://www.example.com
        "400":
          description: Bad request
        "403":
          description: Forbidden
        "404":
          description: Photo not found

      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  securitySchemes:
    apiKey:
      type: apiKey
      name: X-Goog-Api-Key
      in: header
      description: Google Maps Platform API key

  parameters:
    fieldMask:
      name: X-Goog-FieldMask
      in: header
      required: true
      description: >-
        A comma-separated list of place data fields to return. Use field
        masking to specify which fields to include in the response.
        For example: places.displayName,places.formattedAddress. Use *
        to return all fields (not recommended in production).
      schema:
        type: string
      example: "places.displayName,places.formattedAddress,places.location"

    languageCode:
      name: languageCode
      in: query
      description: >-
        The language code (BCP-47) to use for returning results. If not
        specified, results may be in mixed languages.
      schema:
        type: string
      example: "en"

    regionCode:
      name: regionCode
      in: query
      description: >-
        The Unicode country/region code (CLDR) of the location where the
        request is coming from. Used for formatting and biasing.
      schema:
        type: string
      example: "US"

    sessionToken:
      name: sessionToken
      in: query
      description: >-
        A random string that groups an autocomplete session for billing.
        The session begins with an autocomplete request and concludes with
        a place details or address validation call.
      schema:
        type: string

  schemas:
    Place:
      type: object
      description: A complete place representation from the Places API (New)
      properties:
        name:
          type: string
          description: >-
            The resource name of this place in the format
            places/{placeId}.
          example: "places/ChIJN1t_tDeuEmsRUsoyG83frY4"
        id:
          type: string
          description: The unique place ID
          example: "ChIJN1t_tDeuEmsRUsoyG83frY4"
        displayName:
          $ref: "#/components/schemas/LocalizedText"
        types:
          type: array
          description: >-
            A set of type tags for this place. Full list at
            https://developers.google.com/maps/documentation/places/web-service/place-types
          items:
            type: string
          example:
          - restaurant
          - food
          - point_of_interest
          - establishment
        primaryType:
          type: string
          description: The primary type of this place
          example: "restaurant"
        primaryTypeDisplayName:
          $ref: "#/components/schemas/LocalizedText"
        nationalPhoneNumber:
          type: string
          description: The place's phone number in national format
          example: "(02) 9374 4000"
        internationalPhoneNumber:
          type: string
          description: The place's phone number in international format
          example: "+61 2 9374 4000"
        formattedAddress:
          type: string
          description: The full human-readable address for this place
          example: "48 Pirrama Rd, Pyrmont NSW 2009, Australia"
        shortFormattedAddress:
          type: string
          description: A short human-readable address for this place
          example: "48 Pirrama Rd, Pyrmont"
        addressComponents:
          type: array
          description: The individual address components of the place
          items:
            $ref: "#/components/schemas/PlaceAddressComponent"
          example: []
        location:
          $ref: "#/components/schemas/LatLng"
        viewport:
          $ref: "#/components/schemas/Viewport"
        rating:
          type: number
          format: double
          description: The place's rating on a scale of 1.0 to 5.0
          minimum: 1.0
          maximum: 5.0
          example: 4.2
        userRatingCount:
          type: integer
          description: The total number of user ratings
          example: 1234
        googleMapsUri:
          type: string
          format: uri
          description: A URL to the place's page on Google Maps
          example: https://www.example.com
        websiteUri:
          type: string
          format: uri
          description: The place's website URL
          example: https://www.example.com
        regularOpeningHours:
          $ref: "#/components/schemas/OpeningHours"
        currentOpeningHours:
          $ref: "#/components/schemas/OpeningHours"
        priceLevel:
          type: string
          description: The price level of the place
          enum:
          - PRICE_LEVEL_UNSPECIFIED
          - PRICE_LEVEL_FREE
          - PRICE_LEVEL_INEXPENSIVE
          - PRICE_LEVEL_MODERATE
          - PRICE_LEVEL_EXPENSIVE
          - PRICE_LEVEL_VERY_EXPENSIVE
          example: PRICE_LEVEL_UNSPECIFIED
        businessStatus:
          type: string
          description: The business status of the place
          enum:
          - BUSINESS_STATUS_UNSPECIFIED
          - OPERATIONAL
          - CLOSED_TEMPORARILY
          - CLOSED_PERMANENTLY
          example: BUSINESS_STATUS_UNSPECIFIED
        utcOffsetMinutes:
          type: integer
          description: >-
            Number of minutes this place's current timezone is offset
            from UTC
          example: 10
        reviews:
          type: array
          description: Up to 5 reviews for this place
          items:
            $ref: "#/components/schemas/Review"
          example: []
        photos:
          type: array
          description: Photos associated with this place
          items:
            $ref: "#/components/schemas/Photo"
          example: []
        editorialSummary:
          $ref: "#/components/schemas/LocalizedText"
        adrFormatAddress:
          type: string
          description: The place's address in adr microformat
          example: example_value
        iconMaskBaseUri:
          type: string
          format: uri
          description: A URL for an SVG icon mask
          example: https://www.example.com
        iconBackgroundColor:
          type: string
          description: Background color for the icon in hex format
          example: "#FF9E67"
        plusCode:
          $ref: "#/components/schemas/PlusCode"
        accessibilityOptions:
          $ref: "#/components/schemas/AccessibilityOptions"
        parkingOptions:
          $ref: "#/components/schemas/ParkingOptions"
        paymentOptions:
          $ref: "#/components/schemas/PaymentOptions"
        dineIn:
          type: boolean
          description: Whether the place supports dine-in
          example: true
        takeout:
          type: boolean
          description: Whether the place supports takeout
          example: true
        delivery:
          type: boolean
          description: Whether the place supports delivery
          example: true
        curbsidePickup:
          type: boolean
          description: Whether the place supports curbside pickup
          example: true
        reservable:
          type: boolean
          description: Whether the place supports reservations
          example: true
        servesBreakfast:
          type: boolean
          example: true
        servesLunch:
          type: boolean
          example: true
        servesDinner:
          type: boolean
          example: true
        servesBeer:
          type: boolean
          example: true
        servesWine:
          type: boolean
          example: true
        servesVegetarianFood:
          type: boolean

          example: true
    SearchTextRequest:
      type: object
      description: Request body for text search
      properties:
        textQuery:
          type: string
          description: The text query for the search
          example: "pizza in New York"
        includedType:
          type: string
          description: Restrict results to a specific place type
          example: "restaurant"
        languageCode:
          type: string
          description: The language code for results
          example: "en"
        regionCode:
          type: string
          description: The region code for biasing results
          example: "US"
        rankPreference:
          type: string
          description: How results should be ranked
          enum:
          - RELEVANCE
          - DISTANCE
          example: RELEVANCE
        maxResultCount:
          type: integer
          description: >-
            Maximum number of results to return (1-20)
          minimum: 1
          maximum: 20
          example: 10
        locationBias:
          $ref: "#/components/schemas/LocationBias"
        locationRestriction:
          $ref: "#/components/schemas/LocationRestriction"
        priceLevels:
          type: array
          description: Filter results by price level
          items:
            type: string
            enum:
            - PRICE_LEVEL_INEXPENSIVE
            - PRICE_LEVEL_MODERATE
            - PRICE_LEVEL_EXPENSIVE
            - PRICE_LEVEL_VERY_EXPENSIVE
          example: []
        openNow:
          type: boolean
          description: Return only places that are currently open
          example: true
        minRating:
          type: number
          format: double
          description: Filter results to those with at least this rating
          minimum: 0.0
          maximum: 5.0
          example: 42.5
        strictTypeFiltering:
          type: boolean
          description: >-
            If true, only return results that match the includedType exactly
          example: true
      required:
      - textQuery

    SearchNearbyRequest:
      type: object
      description: Request body for nearby search
      properties:
        includedTypes:
          type: array
          description: Place types to include in results
          items:
            type: string
          example:
          - restaurant
        excludedTypes:
          type: array
          description: Place types to exclude from results
          items:
            type: string
          example: []
        includedPrimaryTypes:
          type: array
          description: Primary place types to include
          items:
            type: string
          example: []
        excludedPrimaryTypes:
          type: array
          description: Primary place types to exclude
          items:
            type: string
          example: []
        languageCode:
          type: string
          description: The language code for results
          example: example_value
        regionCode:
          type: string
          description: The region code for biasing results
          example: example_value
        rankPreference:
          type: string
          description: How results should be ranked
          enum:
          - POPULARITY
          - DISTANCE
          example: POPULARITY
        maxResultCount:
          type: integer
          description: Maximum number of results (1-20)
          minimum: 1
          maximum: 20
          example: 10
        locationRestriction:
          $ref: "#/components/schemas/LocationRestriction"
      required:
      - locationRestriction

    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"

    PlacePrediction:
      type: objec

# --- truncated at 32 KB (44 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/google-maps/refs/heads/main/openapi/google-maps-places-api.yml