Text Search (novo)

Selecione a plataforma: Android iOS JavaScript Web Service

Desenvolvedores do Espaço Econômico Europeu (EEE)

Introdução

O Text Search (novo) retorna informações sobre um conjunto de lugares com base em uma string (por exemplo, "pizza em São Paulo", "loja de sapatos perto do Rio de Janeiro" ou "Avenida Brasil, 123"). O serviço responde com uma lista de locais correspondentes à string de texto e a todos os direcionamentos de localização definidos.

Além dos parâmetros obrigatórios, o Text Search (novo) permite refinar consultas usando parâmetros opcionais para melhorar os resultados.

O APIs Explorer permite fazer solicitações em tempo real para que você se familiarize com a API e as opções dela:

Solicitações do Text Search (novo)

Uma solicitação do Text Search (novo) é uma solicitação HTTP POST com o seguinte formato:

https://places.googleapis.com/v1/places:searchText

Transmita todos os parâmetros no corpo da solicitação JSON ou nos cabeçalhos como parte da solicitação POST. Exemplo:

curl -X POST -d '{
  "textQuery" : "Spicy Vegetarian Food in Sydney, Australia"
}' \
-H 'Content-Type: application/json' -H 'X-Goog-Api-Key: API_KEY' \
-H 'X-Goog-FieldMask: places.displayName,places.formattedAddress,places.priceLevel' \
'https://places.googleapis.com/v1/places:searchText'

Respostas da Text Search (novo)

A Text Search (nova) retorna um objeto JSON como resposta. Na resposta:

  • A matriz places contém todos os lugares correspondentes.
  • Cada lugar na matriz é representado por um objeto Place. O objeto Place contém informações detalhadas sobre um único lugar.
  • O FieldMask transmitido na solicitação especifica a lista de campos retornados no objeto Place.
  • Não há garantia de que a lista de lugares retornada será consistente para solicitações idênticas.

O objeto JSON completo está no formato:

{
  "places": [
    {
      object (Place)
    }
  ]
}

Parâmetros obrigatórios

  • FieldMask

    Especifique a lista de campos a serem retornados na resposta criando uma máscara de campo de resposta. Transmita a máscara de campo de resposta ao método usando o parâmetro de URL $fields ou fields ou o cabeçalho HTTP X-Goog-FieldMask. Não há uma lista padrão de campos retornados na resposta. Se você omitir a máscara de campo, o método vai retornar um erro.

    A máscara de campo é uma boa prática de design para garantir que você não solicite dados desnecessários, o que ajuda a evitar tempo de processamento e cobranças de faturamento desnecessários.

    Especifique uma lista separada por vírgulas de tipos de dados de lugar a serem retornados. Por exemplo, para recuperar o nome de exibição e o endereço do lugar.

    X-Goog-FieldMask: places.displayName,places.formattedAddress

    Use * para recuperar todos os campos.

    X-Goog-FieldMask: *

    Especifique um ou mais dos seguintes campos:

    • Os campos a seguir acionam a SKU Text Search Essentials ID Only:

      places.attributions
      places.id
      places.consumerAlert
      places.name*
      nextPageToken
      places.movedPlace
      places.movedPlaceId

      * O campo places.name contém o nome do recurso do lugar no formato places/PLACE_ID. Use places.displayName na SKU Pro para acessar o nome do lugar em texto.

      Para ver uma lista completa de campos e as SKUs associadas, consulte Campos de dados de lugar (novo).

    • Os campos a seguir acionam a SKU Text Search Pro:

      places.accessibilityOptions
      places.addressComponents
      places.addressDescriptor*
      places.adrFormatAddress
      places.businessStatus
      places.containingPlaces
      places.displayName
      places.formattedAddress
      places.googleMapsLinks
      places.googleMapsTypeLabel
      places.googleMapsUri
      places.iconBackgroundColor
      places.iconMaskBaseUri
      places.location
      places.openingDate
      places.photos
      places.plusCode
      places.postalAddress
      places.primaryType
      places.primaryTypeDisplayName
      places.pureServiceAreaBusiness
      places.shortFormattedAddress
      places.searchUri
      places.subDestinations
      places.timeZone
      places.types
      places.utcOffsetMinutes
      places.viewport

      * Os descritores de endereço estão em disponibilidade geral para clientes na Índia e em fase experimental em outros lugares.

      Para ver uma lista completa de campos e as SKUs associadas, consulte Campos de dados de lugar (novo).

    • Os campos a seguir acionam a SKU Text Search Enterprise:

      places.currentOpeningHours
      places.currentSecondaryOpeningHours
      places.internationalPhoneNumber
      places.nationalPhoneNumber
      places.priceLevel
      places.priceRange
      places.rating
      places.regularOpeningHours
      places.regularSecondaryOpeningHours
      places.transitStation
      places.userRatingCount
      places.websiteUri

      Para ver uma lista completa de campos e as SKUs associadas, consulte Campos de dados de lugar (novo).

    • Os campos a seguir acionam a SKU Text Search Enterprise + Atmosphere:

      places.allowsDogs
      places.curbsidePickup
      places.delivery
      places.dineIn
      places.editorialSummary
      places.evChargeAmenitySummary
      places.evChargeOptions
      places.fuelOptions
      places.generativeSummary
      places.goodForChildren
      places.goodForGroups
      places.goodForWatchingSports
      places.liveMusic
      places.menuForChildren
      places.neighborhoodSummary
      places.parkingOptions
      places.paymentOptions
      places.outdoorSeating
      places.reservable
      places.restroom
      places.reviews
      places.reviewSummary
      routingSummaries*
      places.servesBeer
      places.servesBreakfast
      places.servesBrunch
      places.servesCocktails
      places.servesCoffee
      places.servesDessert
      places.servesDinner
      places.servesLunch
      places.servesVegetarianFood
      places.servesWine
      places.takeout

      * Somente Text Search e Nearby Search

      Para ver uma lista completa de campos e as SKUs associadas, consulte Campos de dados de lugar (novo).

  • textQuery

    A string de texto em que a pesquisa será feita. Por exemplo, "restaurante", "Rua Principal, 123" ou "Melhor lugar para visitar em São Francisco". A API retorna as correspondências possíveis de acordo com essa string e ordena os resultados com base na relevância.

    O Text Search (novo) não é destinado a consultas ambíguas, incluindo as seguintes:

    Tipo de consulta Exemplo
    Muitos conceitos ou restrições, como os nomes de vários lugares, vias ou cidades em uma única consulta "Market Street San Francisco San Jose Airport"
    Elementos de endereço postal não representados no Google Maps "A/C João da Silva, Rua Principal, 123"
    "Caixa Postal 13, São Paulo"
    Nomes de empresas, franquias ou categorias combinados com locais onde essas entidades não estão disponíveis "Tesco perto de Dallas, Texas"
    Consultas ambíguas com várias interpretações "Entrega do carregador"
    Nomes históricos que não estão mais em uso "Middlesex United Kingdom"
    Elementos ou intenções não geoespaciais "Quantos barcos estão no porto de Ventura?"
    Nomes não oficiais ou personalizados "The Jenga"
    "The Helter Skelter"
    Coordenadas de latitude e longitude "37.422131,-122.084801"

Parâmetros opcionais

  • includeFutureOpeningBusinesses

    Se for true, retorna empresas que devem abrir no futuro. O padrão é false.

    Para recuperar o status da empresa, inclua places.businessStatus na máscara de campo da solicitação. Para recuperar a data de abertura prevista da empresa, inclua places.openingDate na máscara de campo da solicitação.

  • includedType

    Prioriza os resultados para lugares que correspondem ao tipo especificado definido pela Tabela A. Só é possível especificar um tipo. Exemplo:

    • "includedType":"bar"
    • "includedType":"pharmacy"

    A Text Search (nova) aplica a filtragem de tipo a determinadas consultas, dependendo da aplicabilidade. Por exemplo, a filtragem de tipo pode não ser aplicada a consultas de endereços específicos ("Rua Principal, 123"), mas quase sempre é aplicada a consultas categóricas ("lojas próximas" ou "shoppings").

    Para aplicar a filtragem de tipo a todas as consultas, defina strictTypeFiltering como true.

  • includePureServiceAreaBusinesses

    Se definido como true, a resposta inclui empresas que visitam ou atendem clientes diretamente, mas não têm um local físico. Se definido como false, a API retorna apenas empresas com um local físico.

  • languageCode

    O idioma em que os resultados serão retornados.

    • Consulte a lista de idiomas compatíveis. O Google atualiza os idiomas compatíveis com frequência, então esta lista pode não estar completa.
    • Se languageCode não for fornecido, a API usará en como padrão. Se você especificar um código de idioma inválido, a API vai retornar um erro INVALID_ARGUMENT.
    • A API faz o possível para fornecer um endereço que seja legível para o usuário e os moradores locais. Para isso, ele retorna endereços no idioma local, transliterados para um script legível pelo usuário, se necessário, de acordo com o idioma preferido. Todos os outros endereços são retornados no idioma preferencial. Os componentes de endereço são todos retornados no mesmo idioma, que é escolhido no primeiro componente.
    • Se um nome não estiver disponível no idioma preferido, a API vai usar a correspondência mais próxima.
    • O idioma preferencial tem uma pequena influência no conjunto de resultados que a API escolhe retornar e na ordem em que eles são retornados. O geocodificador interpreta abreviações de maneira diferente dependendo do idioma, como as abreviações de tipos de rua ou sinônimos que podem ser válidos em um idioma, mas não em outro.

  • locationBias

    Especifica uma área para pesquisar. Esse local serve como uma polarização, o que significa que os resultados em torno do local especificado podem ser retornados, incluindo resultados fora da área especificada.

    É possível especificar locationRestriction ou locationBias, mas não ambos. Pense em locationRestriction como a especificação da região em que os resultados precisam estar e em locationBias como a especificação da região em que os resultados provavelmente estarão dentro ou perto, mas podem estar fora da área.

    Especifique a região como uma janela de visualização retangular ou como um círculo.

    • Um círculo é definido pelo ponto central e pelo raio em metros. O raio precisa estar entre 0,0 e 50.000,0, inclusive. O raio padrão é 0,0. Exemplo:

      "locationBias": {
  "circle": {
    "center": {
      "latitude": 37.7937,
      "longitude": -122.3965
    },
    "radius": 500.0
  }
}

    • Um retângulo é uma janela de visualização de latitude-longitude, representada como dois pontos diagonalmente opostos, um baixo e um alto. O ponto baixo marca o canto sudoeste do retângulo, e o ponto alto representa o canto nordeste.

      Uma janela de visualização é considerada uma região fechada, ou seja, inclui o limite. Os limites de latitude precisam estar entre -90 e 90 graus, e os limites de longitude precisam estar entre -180 e 180 graus:

      • Se low = high, a janela de visualização consiste nesse único ponto.
      • Se low.longitude > high.longitude, o intervalo de longitude será invertido (a janela de visualização cruza a linha de longitude de 180 graus).
      • Se low.longitude = -180 graus e high.longitude = 180 graus, a janela de visualização inclui todas as longitudes.
      • Se low.longitude = 180 graus e high.longitude = -180 graus, o intervalo de longitude fica vazio.
      • Se low.latitude > high.latitude, o intervalo de latitude estará vazio.

      Os valores baixo e alto precisam ser preenchidos, e a caixa representada não pode estar vazia. Uma janela de visualização vazia resulta em um erro.

      Por exemplo, esta janela de visualização inclui totalmente a cidade de Nova York:

      "locationBias": {
  "rectangle": {
    "low": {
      "latitude": 40.477398,
      "longitude": -74.259087
    },
    "high": {
      "latitude": 40.91618,
      "longitude": -73.70018
    }
  }
}

  • locationRestriction

    Especifica uma área para pesquisar somente consultas categóricas, que podem retornar vários lugares (por exemplo, "Restaurantes em São Paulo" ou "Shopping centers"). Os resultados fora da área especificada não são retornados.

    Especifique a região como uma janela de visualização retangular. Para ver um exemplo de como definir a janela de visualização, consulte a descrição de locationBias.

    É possível especificar locationRestriction ou locationBias, mas não ambos. Pense em locationRestriction como a especificação da região em que os resultados precisam estar e em locationBias como a especificação da região em que os resultados provavelmente estarão dentro ou perto, mas podem estar fora da área.

  • evOptions

    Especifica parâmetros para identificar conectores de carregamento de veículos elétricos (VE) disponíveis e taxas de carregamento.

    • connectorTypes

      Filtra pelo tipo de conector de carregamento de VE disponível em um lugar. Um lugar que não aceita nenhum dos tipos de conector será filtrado. Os tipos de conector de carregamento de VE compatíveis incluem carregadores combinados (CA e CC), carregadores Tesla, carregadores compatíveis com GB/T (para carregamento rápido de VE na China) e carregadores de tomada de parede. Para mais informações, consulte a documentação de referência.

      • Para filtrar os resultados de um conector compatível específico, defina connectorTypes como esse valor. Por exemplo, para encontrar conectores J1772 tipo 1, defina connectorTypes como EV_CONNECTOR_TYPE_J1772.
      • Para filtrar resultados de conectores não compatíveis, defina connectorTypes como EV_CONNECTOR_TYPE_OTHER.
      • Para filtrar os resultados de qualquer tipo de conector que seja uma tomada de parede, defina connectorTypes como EV_CONNECTOR_TYPE_UNSPECIFIED_WALL_OUTLET.
      • Para filtrar os resultados de qualquer tipo de conector, defina connectorTypes como EV_CONNECTOR_TYPE_UNSPECIFIED ou não defina um valor para connectorTypes.

    • minimumChargingRateKw

      Filtra lugares pela taxa mínima de carregamento de VE em quilowatts (kW). Todos os lugares com uma taxa de carregamento menor que a mínima são filtrados. Por exemplo, para encontrar carregadores de VE com taxas de carregamento de pelo menos 10 kW, defina esse parâmetro como "10".

  • minRating

    Restringe os resultados apenas àqueles com uma avaliação média de usuários maior ou igual a esse limite. Os valores precisam estar entre 0,0 e 5,0 (inclusive) em incrementos de 0,5. Por exemplo: 0, 0,5, 1,0, ... , 5,0 inclusive. Os valores são arredondados para o 0,5 mais próximo. Por exemplo, um valor de 0,6 elimina todos os resultados com uma classificação inferior a 1,0.

  • openNow

    Se true, retorna apenas os lugares que estão abertos no momento em que a consulta é enviada. Se for false, retornar todas as empresas, independentemente do status de abertura. Os lugares que não especificam o horário de funcionamento no banco de dados do Google Places serão retornados se você definir esse parâmetro como false.

  • pageSize

    Especifica o número de resultados, entre 1 e 20, que serão exibidos em cada página. Por exemplo, definir um valor de pageSize de 5 retorna até 5 resultados na primeira página. Se a consulta puder retornar mais resultados, a resposta vai incluir um nextPageToken que pode ser transmitido em uma solicitação subsequente para acessar a próxima página.

    Esse campo substitui o campo maxResultCount descontinuado. Se você especificar pageSize e maxResultCount, a API vai usar pageSize e ignorar maxResultCount.

  • pageToken

    Especifica o nextPageToken do corpo de resposta da página anterior.

  • priceLevels

    Restringe a pesquisa a lugares marcados com determinados níveis de preço. O padrão é selecionar todos os níveis de preço.

    Os níveis de preço podem ser esperados para lugares dos seguintes tipos:

    Os lugares de tipos não aceitos não serão incluídos na resposta se priceLevels for especificado.

    Especifique uma matriz de um ou mais valores definidos por PriceLevel.

    Exemplo:

    "priceLevels":["PRICE_LEVEL_INEXPENSIVE", "PRICE_LEVEL_MODERATE"]

  • rankPreference

    Especifica como os resultados são classificados na resposta com base no tipo de consulta:

    • Para uma consulta categórica, como "Restaurantes em São Paulo", RELEVANCE (classificar resultados por relevância da pesquisa) é o padrão. Você pode definir rankPreference como RELEVANCE ou DISTANCE (classificar os resultados por distância).
    • Para uma consulta não categórica, como "Mountain View, CA", recomendamos que você deixe rankPreference sem definição.

  • regionCode

    O código de região usado para formatar a resposta, especificado como um valor de código CLDR de dois caracteres. Esse parâmetro também pode ter um efeito de viés nos resultados da pesquisa. Não há valor padrão.

    Se o nome do país do campo formattedAddress na resposta corresponder a regionCode, o código do país será omitido de formattedAddress. Esse parâmetro não tem efeito em adrFormatAddress, que sempre inclui o nome do país quando disponível, ou em shortFormattedAddress, que nunca o inclui.

    A maioria dos códigos CLDR é idêntica aos códigos ISO 3166-1, com algumas exceções notáveis. Por exemplo, o ccTLD do Reino Unido é "uk" (.co.uk), enquanto o código ISO 3166-1 é "gb" (tecnicamente para a entidade "Reino Unido da Grã-Bretanha e Irlanda do Norte"). O parâmetro pode afetar os resultados com base na legislação aplicável.

  • strictTypeFiltering

    Usado com o parâmetro includedType. Quando definido como true, somente os lugares que correspondem aos tipos especificados por includedType são retornados. Quando é falso (o padrão), a resposta pode conter lugares que não correspondem aos tipos especificados.

Exemplos de Text Search (novo)

Encontrar um lugar por string de consulta

O exemplo a seguir mostra uma solicitação de Text Search (novo) para "comida vegetariana apimentada em Sydney, Austrália":

curl -X POST -d '{
  "textQuery" : "Spicy Vegetarian Food in Sydney, Australia"
}' \
-H 'Content-Type: application/json' -H 'X-Goog-Api-Key: API_KEY' \
-H 'X-Goog-FieldMask: places.displayName,places.formattedAddress' \
'https://places.googleapis.com/v1/places:searchText'

O cabeçalho X-Goog-FieldMask especifica que a resposta contém os seguintes campos de dados: places.displayName,places.formattedAddress. A resposta é no formato:

{
  "places": [
    {
      "formattedAddress": "367 Pitt St, Sydney NSW 2000, Australia",
      "displayName": {
        "text": "Mother Chu's Vegetarian Kitchen",
        "languageCode": "en"
      }
    },
    {
      "formattedAddress": "175 First Ave, Five Dock NSW 2046, Australia",
      "displayName": {
        "text": "Veggo Sizzle - Vegan & Vegetarian Restaurant, Five Dock, Sydney",
        "languageCode": "en"
      }
    },
    ...
  ]
}

Adicione mais tipos de dados à máscara de campo para retornar outras informações. Por exemplo, adicione places.types,places.websiteUri para incluir o tipo de restaurante e o endereço da Web na resposta:

curl -X POST -d '{
  "textQuery" : "Spicy Vegetarian Food in Sydney, Australia"
}' \
-H 'Content-Type: application/json' -H 'X-Goog-Api-Key: API_KEY' \
-H 'X-Goog-FieldMask: places.displayName,places.formattedAddress,places.types,places.websiteUri' \
'https://places.googleapis.com/v1/places:searchText'

A resposta agora está no formato:

{
  "places": [
    {
      "types": [
        "vegetarian_restaurant",
        "vegan_restaurant",
        "chinese_restaurant",
        "restaurant",
        "food",
        "point_of_interest",
        "establishment"
      ],
      "formattedAddress": "367 Pitt St, Sydney NSW 2000, Australia",
      "websiteUri": "http://www.motherchusvegetarian.com.au/",
      "displayName": {
        "text": "Mother Chu's Vegetarian Kitchen",
        "languageCode": "en"
      }
    },
    {
      "types": [
        "vegan_restaurant",
        "thai_restaurant",
        "vegetarian_restaurant",
        "indian_restaurant",
        "italian_restaurant",
        "american_restaurant",
        "restaurant",
        "food",
        "point_of_interest",
        "establishment"
      ],
      "formattedAddress": "175 First Ave, Five Dock NSW 2046, Australia",
      "websiteUri": "http://www.veggosizzle.com.au/",
      "displayName": {
        "text": "Veggo Sizzle - Vegan & Vegetarian Restaurant, Five Dock, Sydney",
        "languageCode": "en"
      }
    },
    ...
  ]
}

Filtrar lugares por nível de preço

Use a opção priceLevel para filtrar os resultados para restaurantes definidos como baratos ou moderadamente caros:

curl -X POST -d '{
  "textQuery" : "Spicy Vegetarian Food in Sydney, Australia",
  "priceLevels":["PRICE_LEVEL_INEXPENSIVE", "PRICE_LEVEL_MODERATE"]
}' \
-H 'Content-Type: application/json' -H 'X-Goog-Api-Key: API_KEY' \
-H 'X-Goog-FieldMask: places.displayName,places.formattedAddress,places.priceLevel' \
'https://places.googleapis.com/v1/places:searchText'

Este exemplo também usa o cabeçalho X-Goog-FieldMask para adicionar o campo de dados places.priceLevel à resposta, para que ele fique no formato:

{
  "places": [
    {
      "formattedAddress": "367 Pitt St, Sydney NSW 2000, Australia",
      "priceLevel": "PRICE_LEVEL_MODERATE",
      "displayName": {
        "text": "Mother Chu's Vegetarian Kitchen",
        "languageCode": "en"
      }
    },
    {
      "formattedAddress": "115 King St, Newtown NSW 2042, Australia",
      "priceLevel": "PRICE_LEVEL_MODERATE",
      "displayName": {
        "text": "Green Mushroom",
        "languageCode": "en"
      }
    },
    ...
  ]
}

Adicione outras opções para refinar sua pesquisa, como includedType, minRating, rankPreference, openNow e outros parâmetros descritos em Parâmetros opcionais.

Restringir a pesquisa a uma área específica

Use locationRestriction ou locationBias, mas não ambos, para restringir uma pesquisa a uma área. Pense em locationRestriction como a especificação da região em que os resultados precisam estar e em locationBias como a especificação da região em que os resultados precisam estar próximos, mas podem estar fora da área.

Restringir área usando locationRestriction

Use o parâmetro locationRestriction para restringir os resultados da consulta a uma região específica. No corpo da solicitação, especifique os valores de latitude e longitude de low e high que definem o limite da região.

O exemplo a seguir mostra uma solicitação do Text Search (novo) para "comida vegetariana" na cidade de Nova York. Essa solicitação retorna apenas os 10 primeiros resultados de lugares que estão abertos.

curl -X POST -d '{
  "textQuery" : "vegetarian food",
  "pageSize" : "10",
  "locationRestriction": {
    "rectangle": {
      "low": {
        "latitude": 40.477398,
        "longitude": -74.259087
      },
      "high": {
        "latitude": 40.91618,
        "longitude": -73.70018
      }
    }
  }
}' \
  -H 'Content-Type: application/json' \
  -H 'X-Goog-Api-Key: API_KEY' \
  -H 'X-Goog-FieldMask: places.id,places.formattedAddress' \
  'https://places.googleapis.com/v1/places:searchText'

Definir uma área usando locationBias

O exemplo a seguir mostra uma solicitação de Text Search (novo) para "comida vegetariana" com viés de localização em um raio de 500 metros de um ponto no centro de São Francisco. Essa solicitação retorna apenas os 10 primeiros resultados de lugares que estão abertos.

curl -X POST -d '{
  "textQuery" : "vegetarian food",
  "openNow": true,
  "pageSize": 10,
  "locationBias": {
    "circle": {
      "center": {"latitude": 37.7937, "longitude": -122.3965},
      "radius": 500.0
    }
  },
}' \
-H 'Content-Type: application/json' -H 'X-Goog-Api-Key: API_KEY' \
-H 'X-Goog-FieldMask: places.displayName,places.formattedAddress' \
'https://places.googleapis.com/v1/places:searchText'

Pesquisar carregadores de VE com uma taxa de carregamento mínima

Use minimumChargingRateKw e connectorTypes para pesquisar lugares com carregadores disponíveis que sejam compatíveis com seu VE.

O exemplo a seguir mostra uma solicitação de conectores de carregamento de VE do tipo 1 Tesla e J1772 com uma taxa de carregamento mínima de 10 kW em Mountain View, CA. Apenas quatro resultados são retornados.

curl -X POST -d '{
    "textQuery": "EV Charging Station Mountain View",
    "pageSize": 4,
    "evOptions": {
      "minimumChargingRateKw": 10,
      "connectorTypes": ["EV_CONNECTOR_TYPE_J1772","EV_CONNECTOR_TYPE_TESLA"]
    }
  }' \
-H 'Content-Type: application/json' -H 'X-Goog-Api-Key: API_KEY' \
-H "X-Goog-FieldMask: places.displayName,places.evChargeOptions" \
'https://places.googleapis.com/v1/places:searchText'

A solicitação retorna a seguinte resposta:

{
  "places": [
    {
      "displayName": {
        "text": "EVgo Charging Station",
        "languageCode": "en"
      },
      "evChargeOptions": {
        "connectorCount": 16,
        "connectorAggregation": [
          {
            "type": "EV_CONNECTOR_TYPE_CHADEMO",
            "maxChargeRateKw": 100,
            "count": 8,
            "availableCount": 5,
            "outOfServiceCount": 0,
            "availabilityLastUpdateTime": "2024-01-10T19:10:00Z"
          },
          {
            "type": "EV_CONNECTOR_TYPE_CCS_COMBO_1",
            "maxChargeRateKw": 100,
            "count": 2,
            "availableCount": 2,
            "outOfServiceCount": 0,
            "availabilityLastUpdateTime": "2024-01-10T19:10:00Z"
          },
          ...
        ]
      }
    },
    {
      "displayName": {
        "text": "EVgo Charging Station",
        "languageCode": "en"
      },
      "evChargeOptions": {
        "connectorCount": 6,
        "connectorAggregation": [
          {
            "type": "EV_CONNECTOR_TYPE_CCS_COMBO_1",
            "maxChargeRateKw": 100,
            "count": 4,
            "availableCount": 3,
            "outOfServiceCount": 0,
            "availabilityLastUpdateTime": "2024-01-10T19:10:00Z"
          },
          {
            "type": "EV_CONNECTOR_TYPE_CCS_COMBO_1",
            "maxChargeRateKw": 350,
            "count": 2,
            "availableCount": 0,
            "outOfServiceCount": 2,
            "availabilityLastUpdateTime": "2024-01-10T19:10:00Z"
          }
        ]
      }
    },
    ...
  ]
}

Pesquisar empresas de serviço local

Use o parâmetro includePureServiceAreaBusinesses para pesquisar empresas sem um endereço de serviço físico (por exemplo, um serviço de limpeza móvel ou um food truck).

O exemplo a seguir mostra uma solicitação de encanadores em São Francisco:

curl -X POST -d '{
  "textQuery" : "plumber San Francisco",
  "includePureServiceAreaBusinesses": true
}' \
-H 'Content-Type: application/json' -H 'X-Goog-Api-Key: API_KEY' \
-H 'X-Goog-FieldMask: places.displayName,places.formattedAddress' \
'https://places.googleapis.com/v1/places:searchText'

Na resposta, as empresas sem um endereço de serviço físico não incluem o campo formattedAddress:

{
  "places": [
    {
      "formattedAddress": "3450 Sacramento St #204, San Francisco, CA 94118, USA",
      "displayName": {
        "text": "Advanced Plumbing & Drain",
        "languageCode": "en"
      }
    },
    {
      "displayName": {
        "text": "Starboy Plumbing Inc.",
        "languageCode": "en"
      }
    },
    ...
  ]
}

Especificar um número de resultados a serem retornados por página

Use o parâmetro pageSize para especificar um número de resultados a serem retornados por página. O parâmetro nextPageToken no corpo da resposta fornece um token que pode ser usado em chamadas subsequentes para acessar a próxima página de resultados.

O exemplo a seguir mostra uma solicitação de "pizza em Nova York" limitada a cinco resultados por página:

 curl -X POST -d '{
  "textQuery": "pizza in New York",
  "pageSize": 5
  }' \
-H 'Content-Type: application/json' -H 'X-Goog-Api-Key: API_KEY' \
-H "X-Goog-FieldMask: places.id,nextPageToken" \
'https://places.googleapis.com/v1/places:searchText'

{
  "places": [
    {
      "id": "ChIJifIePKtZwokRVZ-UdRGkZzs"
    },
    {
      "id": "ChIJPxPd_P1YwokRfzLhSiACEoU"
    },
    ...
  ],
  "nextPageToken": "AeCrKXsZWzNVbPzO-MRWPu52jWO_Xx8aKwOQ69_Je3DxRpfdjClq8Ekwh3UcF2h2Jn75kL6PtWLGV4ecQri-GEUKN_OFpJkdVc-JL4Q"
}

Para acessar a próxima página de resultados, use pageToken para transmitir o nextPageToken no corpo da solicitação:

 curl -X POST -d '{
  "textQuery": "pizza in New York",
  "pageSize": 5,
  "pageToken": "AeCrKXsZWzNVbPzO-MRWPu52jWO_Xx8aKwOQ69_Je3DxRpfdjClq8Ekwh3UcF2h2Jn75kL6PtWLGV4ecQri-GEUKN_OFpJkdVc-JL4Q"
  }' \
-H 'Content-Type: application/json' -H 'X-Goog-Api-Key: API_KEY' \
-H "X-Goog-FieldMask: places.id,nextPageToken" \
'https://places.googleapis.com/v1/places:searchText'

{
  "places": [
    {
      "id": "ChIJL-LN1N1ZwokR8K2jACu6Ydw"
    },
    {
      "id": "ChIJjaD94kFZwokR-20CXqlpy_4"
    },
    ...
  ],
  "nextPageToken": "AeCrKXvPd6uUy-oj96W2OaqEe2pUD8QTxOM8-sKfUcFsC9t2Wey5qivrKGoGSxcZnyc7RPmaFfAktslrKbUh31ZDTkL0upRmaxA7c_c"
}

Receber descritores de endereço

Os descritores de endereço fornecem informações relacionais sobre a localização de um lugar, incluindo pontos de referência próximos e áreas que o contêm.

O exemplo a seguir mostra uma solicitação do Text Search (novo) para lugares perto de um shopping em San José. Neste exemplo, você inclui addressDescriptors na máscara de campo:

curl -X POST -d '{
  "textQuery": "clothes",
  "maxResultCount": 5,
  "locationBias": {
    "circle": {
      "center": {
        "latitude": 37.321328,
        "longitude": -121.946275
      }
    }
  },
  "rankPreference":"RANK_PREFERENCE_UNSPECIFIED"
}' \
-H 'Content-Type: application/json' \
-H "X-Goog-Api-Key: API_KEY" \
-H "X-Goog-FieldMask: places.displayName,places.addressDescriptor" \
https://places.googleapis.com/v1/places:searchText

A resposta inclui o lugar especificado na solicitação, uma lista de pontos de referência próximos e a distância deles até o lugar, além de uma lista de áreas e a relação de contenção delas com o lugar:

  {
  "places": [
    {
      "displayName": {
        "text": "Urban Outfitters",
        "languageCode": "en"
      },
      "addressDescriptor": {
        "landmarks": [
          {
            "name": "places/ChIJVVVVUB7Lj4ARXyb4HFVDV8s",
            "placeId": "ChIJVVVVUB7Lj4ARXyb4HFVDV8s",
            "displayName": {
              "text": "Westfield Valley Fair",
              "languageCode": "en"
            },
            "types": [
              "clothing_store",
              "department_store",
              "establishment",
              "food",
              "movie_theater",
              "point_of_interest",
              "restaurant",
              "shoe_store",
              "shopping_mall",
              "store"
            ],
            "spatialRelationship": "WITHIN",
            "straightLineDistanceMeters": 133.72855
          },
          {
            "name": "places/ChIJ62_oCR7Lj4AR_MGWkSPotD4",
            "placeId": "ChIJ62_oCR7Lj4AR_MGWkSPotD4",
            "displayName": {
              "text": "Nordstrom",
              "languageCode": "en"
            },
            "types": [
              "clothing_store",
              "department_store",
              "establishment",
              "point_of_interest",
              "shoe_store",
              "store"
            ],
            "straightLineDistanceMeters": 250.99161
          },
          ...
        ],
        "areas": [
          {
            "name": "places/ChIJb3F-EB7Lj4ARnHApQ_Hu1gI",
            "placeId": "ChIJb3F-EB7Lj4ARnHApQ_Hu1gI",
            "displayName": {
              "text": "Westfield Valley Fair",
              "languageCode": "en"
            },
            "containment": "WITHIN"
          },
          {
            "name": "places/ChIJXYuykB_Lj4AR1Ot8nU5q26Q",
            "placeId": "ChIJXYuykB_Lj4AR1Ot8nU5q26Q",
            "displayName": {
              "text": "Valley Fair",
              "languageCode": "en"
            },
            "containment": "WITHIN"
          },
          ...
        ]
      }
    },
    ...
  ]
}

Encontrar empresas que vão abrir no futuro

O exemplo a seguir mostra uma solicitação do Text Search (novo) para empresas que serão abertas em New Meadows, Idaho:

curl -X POST \
-H "Content-Type: application/json" \
-H "X-Goog-Api-Key: API_KEY" \
-H "X-Goog-FieldMask: places.id,places.displayName,places.businessStatus,places.openingDate" \
-d '{
  "textQuery": "Roberts Greenhouse and Tree Farm",
  "includeFutureOpeningBusinesses": true,
  "maxResultCount": 20,
  "locationBias": {
    "circle": {
      "center": {"latitude": 44.9755100, "longitude": -116.2842180},
      "radius": 20
    }
  }
}' \
"https://places.googleapis.com/v1/places:searchText"

A resposta inclui empresas que serão abertas no futuro, além do status e da data de abertura prevista:

{
  "places": [
    {
      "id": "ChIJp1-VoKWJplQRMz8g-7Wa3Do",
      "businessStatus": "FUTURE_OPENING",
      "displayName": {
        "text": "Roberts Greenhouse and Tree Farm",
        "languageCode": "en"
      },
      "openingDate": {
        "year": 2026,
        "month": 4,
        "day": 15
      }
    }
  ]
}

Receber informações sobre estações de transporte público

Use o Text Search (novo) para encontrar estações de transporte público. O corpo da resposta inclui informações sobre a estação, como o nome, as empresas de transporte público afiliadas e as linhas de transporte público que atendem a estação. Além disso, a resposta inclui um ícone de veículo e cores que você pode usar para exibir as informações da estação de transporte público.

O exemplo a seguir mostra uma solicitação para "Grand Central Station":

curl -X POST \
-H "Content-Type: application/json" \
-H "X-Goog-Api-Key: API_KEY" \
-H "X-Goog-FieldMask: places.id,places.displayName,places.transitStation" \
-d '{
  "textQuery": "Grand Central Station"
}' \
"https://places.googleapis.com/v1/places:searchText"

O corpo da resposta inclui informações sobre cada estação dentro do raio, as linhas atendidas pela estação, os alertas emitidos pelas empresas de transporte público nessa parada e informações de partida:

{
  "places": [
    {
      "id": "ChIJhRwB-yFawokRi0AhGH87UTc",
      "displayName": {
        "text": "Grand Central",
        "languageCode": "en"
      },
      "transitStation": {
        "displayName": {
          "text": "Grand Central",
          "languageCode": "en"
        },
        "agencies": [
          {
            "displayName": {
              "text": "Metro-North Railroad",
              "languageCode": "en"
            },
            "url": "http://www.mta.info/mnr",
            "lines": [
              {
                "id": "ChIJOXpD29y2wokRryDO0CocwK0",
                "vehicleType": "HEAVY_RAIL",
                "displayName": {
                  "text": "Harlem",
                  "languageCode": "en"
                },
                "textColor": "#FFFFFF",
                "backgroundColor": "#0061AA",
                "vehicleIcon": {
                  "url": "https://maps.gstatic.com/mapfiles/transit/iw2/svg/rail2.svg"
                },
                "alerts": [
                  {
                    "effect": "OTHER",
                    "texts": [
                      {
                        "headline": {
                          "text": "Information",
                          "languageCode": "en"
                        },
                        "summary": {
                          "text": "Temporary platforms are in place at Botanical Garden, Williams Bridge, and Woodlawn for northbound travel. Build in extra travel time to reach the platform.",
                          "languageCode": "en"
                        },
                        "fullDescription": {
                          "text": "What's Happening? We are renovating some Harlem Line stations in the Bronx. Learn more about the project here.",
                          "languageCode": "en"
                        }
                      }
                    ],
                    "detailsUrls": [
                      {
                        "url": "https://new.mta.info/"
                      }
                    ],
                    "cause": "OTHER_CAUSE",
                    "startTime": "2026-04-16T04:00:00Z",
                    "endTime": "2026-12-01T04:45:00Z",
                    "attribution": {
                      "link": {
                        "text": "new.mta.info",
                        "url": "https://new.mta.info/"
                      }
                    },
                    "createTime": "2026-05-15T22:39:30Z",
                    "severityLevel": "INFO"
                  }
                ]
              },
              ...
            ]
          },
          ...
        ]
        "stops": [
          {
            "id": "ChIJOfdrigFZwokRJPllLwfPrJY",
            "location": {
              "latitude": 40.752823,
              "longitude": -73.977195999999992
            },
            "wheelchairAccessibleEntrance": true
          }
        ],
        "departureBoards": [
          {
            "displayType": "TIME_CENTRIC",
            "rows": [
              {
                "departures": [
                  {
                    "timedDeparture": {
                      "scheduledTime": "2026-05-15T22:42:00Z",
                      "timingType": "SCHEDULED",
                      "predictedTime": "2026-05-15T22:42:00Z",
                      "updateTime": "2026-05-15T22:38:50Z"
                    },
                    "originallyScheduledStopId": "ChIJOfdrigFZwokRJPllLwfPrJY",
                    "lineId": "ChIJAfBuQhwg6IkRYnFpClHxFrM"
                  }
                ]
              },
              ...
            ]
          }
        ]
      }
    },
    {
      "id": "ChIJ_4EAi-pZwokRWe5T1JmmWmc",
      "displayName": {
        "text": "Grand Central Station",
        "languageCode": "en"
      }
    }
  ]
}

Receber entradas e pontos de navegação

É possível solicitar entradas e pontos de navegação para um destino. As entradas definem os pontos de entrada e saída de um lugar (por exemplo, portões diferentes em um aeroporto ou shopping). Os pontos de navegação definem locais na via onde a navegação deve terminar, o que é útil para direcionar os usuários ao lado correto da via ou a um ponto de desembarque específico.

Os pontos de navegação retornam um navigationPointToken. Você pode transmitir esse token para o SDK de navegação (disponível para Android ou iOS) ou para a API Routes para orientar os motoristas até esse local específico. Para mais informações, consulte Tokens de ponto de navegação.

O exemplo a seguir mostra uma solicitação de Text Search (novo) para "Aeroporto Internacional de São Francisco" que inclui entrances e navigationPoints na máscara de campo:

curl -X POST \
-H "Content-Type: application/json" \
-H "X-Goog-Api-Key: API_KEY" \
-H "X-Goog-FieldMask: places.id,places.displayName,places.entrances,places.navigationPoints" \
-d '{
  "textQuery": "San Francisco International Airport",
  "pageSize": 1
}' \
"https://places.googleapis.com/v1/places:searchText"

A resposta inclui as entradas e os pontos de navegação do lugar:

{
  "places": [
    {
      "id": "ChIJVVVVVYx3j4ARP-3NGldc8qQ",
      "displayName": {
        "text": "San Francisco International Airport",
        "languageCode": "en"
      },
      "entrances": [
        {
          "location": {
            "latitude": 37.6172154,
            "longitude": -122.3839724
          }
        },
        {
          "location": {
            "latitude": 37.6174073,
            "longitude": -122.384196
          }
        },
        ...
      ],
      "navigationPoints": [
        {
          "navigationPointToken": "ChIJoioBjMLOQkAR0A3yH_eYXsA...",
          "displayName": {
            "text": "International Terminal Departures Level",
            "languageCode": "en"
          },
          "location": {
            "latitude": 37.6153121,
            "longitude": -122.3900833
          },
          "travelModes": ["WALK"]
        },
        {
          "navigationPointToken": "ChIJy5JKws_OQkAROx0jNN2YXsA...",
          "displayName": {
            "text": "Domestic Garage - SFO Short Term Parking",
            "languageCode": "en"
          },
          "location": {
            "latitude": 37.6157153,
            "longitude": -122.3885012
          },
          "travelModes": ["DRIVE", "WALK"],
          "usages": ["PARKING"]
        },
        ...
      ]
    }
  ]
}

Confira!

O APIs Explorer permite que você faça solicitações de amostra para se familiarizar com a API e as opções dela.

  1. Selecione o ícone da API api no lado direito da página.

  2. Se quiser, edite os parâmetros da solicitação.

  3. Selecione o botão Executar. Na caixa de diálogo, escolha a conta que você quer usar para fazer a solicitação.

  4. No painel do APIs Explorer, selecione o ícone de tela cheia fullscreen para expandir a janela do APIs Explorer.