Esta página foi traduzida pela API Cloud Translation.

Pesquisa de local próximo (Novo)

Selecione a plataforma: Android iOS JavaScript Web Service

Uma solicitação de Nearby Search (novo) recebe um ou mais tipos de lugar e retorna uma lista de lugares correspondentes na área especificada. Uma máscara de campo que especifique um ou mais tipos de dados é necessária. A Pesquisa nas proximidades (nova) só aceita solicitações POST.

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

Faça um teste

Teste a demonstração interativa para conferir os resultados da Pesquisa por voz (nova) exibidos em um mapa.

Solicitações do Nearby Search (novo)

Uma solicitação de Pesquisa nas proximidades (nova) é uma solicitação HTTP POST para um URL no seguinte formato:

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

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 '{
  "includedTypes": ["restaurant"],
  "maxResultCount": 10,
  "locationRestriction": {
    "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" \
https://places.googleapis.com/v1/places:searchNearby

Respostas do Nearby Search (novo)

A Pesquisa nas proximidades (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.

O objeto JSON completo tem este 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 para o 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.

O mascaramento 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 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
```
Observação : não é permitido usar espaços em nenhum lugar da lista de campos.

Use * para recuperar todos os campos.
```
X-Goog-FieldMask: *
```
O caractere curinga "*" seleciona todos os campos. No entanto, embora esse curinga possa ser usado no desenvolvimento, o Google desencoraja o uso da máscara de campo de resposta curinga (*) na produção devido à grande quantidade de dados que podem ser retornados.

Outras orientações para usar places.iconMaskBaseUri e places.iconBackgroundColor podem ser encontradas na seção Ícones de lugar.

Especifique um ou mais dos seguintes campos:
- Os campos a seguir acionam a SKU Nearby Search (Basic):
  
  places.accessibilityOptions, places.addressComponents, places.adrFormatAddress, places.attributions, places.businessStatus, places.containingPlaces, places.displayName, places.formattedAddress, places.googleMapsLinks^*, places.googleMapsUri, places.iconBackgroundColor, places.iconMaskBaseUri, places.id, places.location, places.name^**, places.photos, places.plusCode, places.primaryType, places.primaryTypeDisplayName, places.pureServiceAreaBusiness, places.shortFormattedAddress, places.subDestinations, places.types, places.utcOffsetMinutes, places.viewport
  
  ^* O campo places.googleMapsLinks está na fase de pré-lançamento do GA4 e não há cobrança, ou seja, o faturamento é de US $0, para uso durante a fase de pré-lançamento.
  
  ^** O campo places.name contém o nome do recurso do lugar no formato: places/PLACE_ID. Use places.displayName para acessar o nome do lugar.
- Os campos a seguir acionam o SKU Nearby Search (Avançado):
  
  places.currentOpeningHours, places.currentSecondaryOpeningHours, places.internationalPhoneNumber, places.nationalPhoneNumber, places.priceLevel, places.priceRange, places.rating, places.regularOpeningHours, places.regularSecondaryOpeningHours, places.userRatingCount, places.websiteUri
- Os campos a seguir acionam o SKU Nearby Search (Preferred):
  
  places.allowsDogs, places.curbsidePickup, places.delivery, places.dineIn, places.editorialSummary, places.evChargeOptions, places.fuelOptions, places.goodForChildren, places.goodForGroups, places.goodForWatchingSports, places.liveMusic, places.menuForChildren, places.parkingOptions, places.paymentOptions, places.outdoorSeating, places.reservable, places.restroom, places.reviews, places.routingSummaries,^* places.servesBeer, places.servesBreakfast, places.servesBrunch, places.servesCocktails, places.servesCoffee, places.servesDessert, places.servesDinner, places.servesLunch, places.servesVegetarianFood, places.servesWine, places.takeout
  
  ^* Somente Pesquisa de texto e Pesquisa por proximidades
locationRestriction

A região a ser pesquisada especificada como um círculo, definida pelo ponto central e raio em metros. O raio precisa estar entre 0,0 e 500.000,0. O raio padrão é 0,0. Você precisa definir um valor maior que 0,0 na solicitação.

Exemplo:
```
"locationRestriction": {
  "circle": {
    "center": {
      "latitude": 37.7937,
      "longitude": -122.3965
    },
    "radius": 500.0
  }
}
```

Parâmetros opcionais

includedTypes/excludedTypes, includedPrimaryTypes/excludedPrimaryTypes

Permite especificar uma lista de tipos de Tabela A usados para filtrar os resultados da pesquisa. É possível especificar até 50 tipos em cada categoria de restrição de tipo.

Observação : os valores na Tabela B são retornados apenas na resposta. Não é possível usar valores na Tabela B como um filtro.

Um lugar só pode ter um tipo principal dos tipos da Tabela A associado a ele. Por exemplo, o tipo principal pode ser "mexican_restaurant" ou "steak_house". Use includedPrimaryTypes e excludedPrimaryTypes para filtrar os resultados no tipo principal de um lugar.

Um lugar também pode ter vários valores de tipo dos tipos da Tabela A associados a ele. Por exemplo, um restaurante pode ter os seguintes tipos: "seafood_restaurant", "restaurant", "food", "point_of_interest" e "establishment". Use includedTypes e excludedTypes para filtrar os resultados na lista de tipos associados a um lugar.

Quando você especifica um tipo primário geral, como "restaurant" ou "hotel", a resposta pode conter lugares com um tipo primário mais específico do que o especificado. Por exemplo, você especifica para incluir um tipo principal de "restaurant". A resposta pode conter lugares com um tipo principal de "restaurant", mas também pode conter lugares com um tipo principal mais específico, como "chinese_restaurant" ou "seafood_restaurant".

Se uma pesquisa for especificada com várias restrições de tipo, apenas os lugares que atenderem a todas as restrições serão retornados. Por exemplo, se você especificar {"includedTypes": ["restaurant"], "excludedPrimaryTypes": ["steak_house"]}, os lugares retornados oferecem serviços relacionados a "restaurant", mas não operam principalmente como "steak_house".

Se você omitir includedTypes, excludedTypes, includedPrimaryTypes e excludedPrimaryTypes da solicitação, a pesquisa vai retornar lugares de todos os tipos dentro dos limites de restrição de local.

includedTypes

Uma lista separada por vírgulas dos tipos de lugar da Tabela A a serem pesquisados. Se esse parâmetro for omitido, lugares de todos os tipos serão retornados.

excludedTypes

Uma lista separada por vírgulas de tipos de lugar da Tabela A a serem excluídos de uma pesquisa.

Se você especificar includedTypes ( como "school") e excludedTypes (como "primary_school") na solicitação, a resposta vai incluir lugares categorizados como "school", mas não como "primary_school". A resposta inclui lugares que correspondem a pelo menos um dos includedTypes e nenhum dos excludedTypes.

Se houver tipos conflitantes, como um tipo que aparece em includedTypes e excludedTypes, um erro INVALID_REQUEST será retornado.

includedPrimaryTypes

Uma lista separada por vírgulas de tipos de lugar principais da Tabela A para incluir em uma pesquisa.

excludedPrimaryTypes

Uma lista separada por vírgulas de tipos de lugar principais da Tabela A a serem excluídos de uma pesquisa.

Se houver tipos principais conflitantes, como um tipo que aparece em includedPrimaryTypes e excludedPrimaryTypes, um erro INVALID_ARGUMENT será retornado.
languageCode

O idioma em que os resultados serão retornados.
- Consulte a lista de idiomas aceitos. O Google atualiza os idiomas suportados com frequência, portanto, esta lista pode não estar completa.
- Se languageCode não for fornecido, a API vai 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 residencial legível tanto para o usuário quanto para os locais. Para atingir esse objetivo, ele retorna os endereços residenciais no idioma local, transliterado para um script legível pelo usuário, se necessário, observando o idioma preferencial. Todos os outros endereços são retornados no idioma preferencial. Os componentes de endereço são todos retornados no mesmo idioma, escolhido pelo primeiro componente.
- Se um nome não estiver disponível no idioma preferencial, a API usará a correspondência mais próxima.
- O idioma preferencial tem uma pequena influência no conjunto de resultados que a API escolhe para retornar e na ordem em que é retornado. O codificador geográfico interpreta abreviações de formas variadas dependendo do idioma, como abreviações de tipos de rua ou sinônimos que podem ser válidos em um idioma, mas não em outros.
maxResultCount

Especifica o número máximo de resultados de lugar a serem retornados. Precisa estar entre 1 e 20 (padrão), inclusive.
rankPreference

O tipo de classificação a ser usado. Se esse parâmetro for omitido, os resultados serão classificados por popularidade. Pode ser um dos seguintes:
- POPULARITY (padrão) Classifica os resultados com base na popularidade.
- DISTANCE Classifica os resultados em ordem crescente de distância a partir da localização especificada.
regionCode

O código de região usado para formatar a resposta, especificado como um valor de código CLDR de dois caracteres. Não há valor padrão.

Se o nome do país do campo formattedAddress na resposta corresponder ao 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, ou em shortFormattedAddress, que nunca 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 da Irlanda do Norte"). O parâmetro pode afetar os resultados com base na legislação aplicável.

Exemplos de Nearby Search (novo)

Encontrar lugares de um tipo

O exemplo a seguir mostra uma solicitação do Nearby Search (Novo) para mostrar os nomes de todos os restaurantes em um raio de 500 metros, definidos por circle:

curl -X POST -d '{
  "includedTypes": ["restaurant"],
  "maxResultCount": 10,
  "locationRestriction": {
    "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" \
https://places.googleapis.com/v1/places:searchNearby

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

{
  "places": [
    {
      "displayName": {
        "text": "La Mar Cocina Peruana",
        "languageCode": "en"
      }
    },
    {
      "displayName": {
        "text": "Kokkari Estiatorio",
        "languageCode": "en"
      }
    },
    {
      "displayName": {
        "text": "Harborview Restaurant & Bar",
        "languageCode": "en"
      }
    },
...
}

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

curl -X POST -d '{
  "includedTypes": ["restaurant"],
  "maxResultCount": 10,
  "locationRestriction": {
    "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,places.types,places.websiteUri" \
https://places.googleapis.com/v1/places:searchNearby

A resposta agora está no formato:

{
  "places": [
    {
      "types": [
        "seafood_restaurant",
        "restaurant",
        "food",
        "point_of_interest",
        "establishment"
      ],
      "formattedAddress": "PIER 1 1/2 The Embarcadero N, San Francisco, CA 94105, USA",
      "websiteUri": "http://lamarsf.com/",
      "displayName": {
        "text": "La Mar Cocina Peruana",
        "languageCode": "en"
      }
    },
    {
      "types": [
        "greek_restaurant",
        "meal_takeaway",
        "restaurant",
        "food",
        "point_of_interest",
        "establishment"
      ],
      "formattedAddress": "200 Jackson St, San Francisco, CA 94111, USA",
      "websiteUri": "https://kokkari.com/",
      "displayName": {
        "text": "Kokkari Estiatorio",
        "languageCode": "en"
      }
    },
...
}

Encontrar lugares de vários tipos

O exemplo a seguir mostra uma solicitação de pesquisa nas proximidades (nova) para os nomes de exibição de todas as lojas de conveniência e bebidas alcoólicas em um raio de 1.000 metros do circle especificado:

curl -X POST -d '{
  "includedTypes": ["liquor_store", "convenience_store"],
  "maxResultCount": 10,
  "locationRestriction": {
    "circle": {
      "center": {
        "latitude": 37.7937,
        "longitude": -122.3965
      },
      "radius": 1000.0
    }
  }
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
-H "X-Goog-FieldMask: places.displayName,places.primaryType,places.types" \
https://places.googleapis.com/v1/places:searchNearby

Neste exemplo, adicionamos places.primaryType e places.types à máscara de campo para que a resposta inclua informações de tipo sobre cada lugar, facilitando a seleção do lugar apropriado nos resultados.

Excluir um tipo de lugar de uma pesquisa

O exemplo a seguir mostra uma solicitação de pesquisa por proximidades (nova) para todos os lugares do tipo "school", excluindo todos os lugares do tipo "primary_school", classificando os resultados por distância:

curl -X POST -d '{
  "includedTypes": ["school"],
  "excludedTypes": ["primary_school"],
  "maxResultCount": 10,
  "locationRestriction": {
    "circle": {
      "center": {
        "latitude": 37.7937,
        "longitude": -122.3965
      },
      "radius": 1000.0
    }
  },
  "rankPreference": "DISTANCE"
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
-H "X-Goog-FieldMask: places.displayName" \
https://places.googleapis.com/v1/places:searchNearby

Pesquisar todos os lugares perto de uma área, classificando por distância

O exemplo a seguir mostra uma solicitação de pesquisa por proximidades (nova) para lugares perto de um ponto no centro de São Francisco. Neste exemplo, você inclui o parâmetro rankPreference para classificar os resultados por distância:

curl -X POST -d '{
  "maxResultCount": 10,
  "rankPreference": "DISTANCE",
  "locationRestriction": {
    "circle": {
      "center": {
        "latitude": 37.7937,
        "longitude": -122.3965
      },
      "radius": 1000.0
    }
  }
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
-H "X-Goog-FieldMask: places.displayName" \
https://places.googleapis.com/v1/places:searchNearby

Confira!

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

Selecione o ícone da API, , no lado direito da página.
Opcionalmente, abra Mostrar parâmetros padrão e defina o parâmetro fields para a máscara de campo.
Se preferir, edite o corpo da solicitação.
Selecione o botão Executar. No pop-up, escolha a conta que você quer usar para fazer a solicitação.
No painel do API Explorer, selecione o ícone de expansão, , para abrir a janela do API Explorer.

Pesquisa de local próximo (Novo)

Solicitações do Nearby Search (novo)

Respostas do Nearby Search (novo)

Parâmetros obrigatórios

FieldMask

locationRestriction

Parâmetros opcionais

includedTypes/excludedTypes, includedPrimaryTypes/excludedPrimaryTypes

includedTypes

excludedTypes

includedPrimaryTypes

excludedPrimaryTypes

languageCode

maxResultCount

rankPreference

regionCode