Esta página foi traduzida pela API Cloud Translation.

Pesquisa de local próximo (Novo)

Uma solicitação de Nearby Search (New) usa um ou mais tipos de lugar e retorna uma lista de lugares correspondentes dentro da área especificada. É necessário usar uma máscara de campo especificando um ou mais tipos de dados. O Nearby Search (novo) só oferece suporte a solicitações POST.

Com o API Explorer, é possível fazer solicitações em tempo real para se familiarizar com a API e as opções dela:

Faça um teste

Solicitações do Nearby Search (novas)

Uma solicitação de Nearby Search (New) é uma solicitação HTTP POST para um URL no 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)

O recurso Nearby Search (New) retorna um objeto JSON como resposta. Na resposta:

A matriz places contém todos os lugares correspondentes.
Cada lugar da matriz é representado por um objeto Place. O objeto Place contém informações detalhadas sobre um único local.
O FieldMask transmitido na solicitação especifica a lista de campos retornados no objeto Place.

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 para o método usando o parâmetro de URL $fields ou fields ou usando 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 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 cobranças de faturamento e tempo de processamento 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 local.
```
X-Goog-FieldMask: places.displayName,places.formattedAddress
```
Observação : não é permitido usar espaços em nenhum lugar na lista de campos.

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

Mais orientações sobre como 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 do Nearby Search (Basic):
  
  places.accessibilityOptions, places.addressComponents, places.adrFormatAddress, places.businessStatus, places.displayName, places.formattedAddress, places.googleMapsUri, places.iconBackgroundColor, places.iconMaskBaseUri, places.id, places.location, places.name^*, places.photos, places.plusCode, places.primaryType, places.primaryTypeDisplayName, places.shortFormattedAddress, places.addressComponents campo: places.adrFormatAddress, places.adrFormatAddress o campo{/1/}.places.nameplaces.subDestinationsplaces.typesplaces.utcOffsetMinutesplaces.viewport
  
  places/PLACE_ID Use places.displayName para acessar o texto do lugar.
- Os campos a seguir acionam a SKU do Nearby Search (avançado):
  
  places.currentOpeningHours, places.currentSecondaryOpeningHours, places.internationalPhoneNumber, places.nationalPhoneNumber, places.priceLevel, places.rating, places.regularOpeningHours, places.regularSecondaryOpeningHours, places.userRatingCount, places.websiteUri
- Os campos a seguir acionam a SKU do Nearby Search (Preferencial):
  
  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.servesBeer, places.delivery, places.delivery, places.delivery, places.delivery, places.servesBreakfastplaces.servesBrunchplaces.servesCocktailsplaces.servesCoffeeplaces.servesDessertsplaces.servesDinnerplaces.servesLunchplaces.servesVegetarianFoodplaces.servesWineplaces.takeout
locationRestriction

A região a ser pesquisada especificada como um círculo, definida pelo ponto central e pelo raio em metros. O raio precisa estar entre 0,0 e 50.000,0. O valor padrão é 0,0. É necessário defini-lo na solicitação como um valor maior que 0,0.

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

Parâmetros opcionais

includeTypes/excludedTypes, includedPrimaryTypes/excludedPrimaryTypes

Permite especificar uma lista de tipos dos tipos da Tabela A usada para filtrar os resultados da pesquisa. Até 50 tipos podem ser especificados 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 da Tabela B como filtro.

Um local só pode ter um único tipo principal dos tipos Tabela A associadas 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 dos tipos 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 uma pesquisa é especificada com várias restrições de tipo, apenas os lugares que atendem a todas as restrições são retornados. Por exemplo, se você especificar {"includedTypes": ["restaurant"], "excludedPrimaryTypes": ["steak_house"]}, os locais retornados fornecerão serviços relacionados a "restaurant", mas não funcionarão principalmente como um "steak_house".

Se você omitir includedTypes, excludedTypes, includedPrimaryTypes e excludedPrimaryTypes da solicitação, a pesquisa retornará lugares para 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 ser pesquisada. Se esse parâmetro for omitido, locais de todos os tipos serão retornados.

excludedTypes

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

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

Se houver algum tipo conflitante, por exemplo, um que apareça em includedTypes e excludedTypes, um erro INVALID_REQUEST será retornado.

includedPrimaryTypes

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

excludedPrimaryTypes

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

Se houver algum tipo principal conflitante, como um que apareça em includedPrimaryTypes e excludedPrimaryTypes, um erro INVALID_ARGUMENT será retornado.
languageCode

O idioma no qual os resultados serão retornados.
- Consulte a lista de idiomas compatíveis. O Google atualiza os idiomas compatíveis com frequência, portanto, essa lista pode não estar completa.
- Se languageCode não for fornecido, o padrão da API será en. Se você especificar um código de idioma inválido, a API retornará um erro INVALID_ARGUMENT.
- A API faz o possível para fornecer um endereço legível tanto para o usuário quanto para os locais. Para isso, ele retorna endereços no idioma local, transliterado para um script que pode ser lido pelo usuário, se necessário, seguindo 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, escolhido no primeiro componente.
- Se um nome não estiver disponível no idioma preferencial, a API usará a correspondência mais próxima.
- A linguagem preferida tem uma pequena influência no conjunto de resultados que a API escolhe retornar e na ordem em que são retornados. O geocodificador interpreta abreviações de maneiras diferentes 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 outro.
maxResultCount

Especifica o número máximo de resultados de lugares a serem retornados. Precisa estar entre 1 e 20 (padrão).
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 do local especificado.
regionCode

O código regional 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 a regionCode, o código do país é 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 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.

Exemplos do Nearby Search (novo)

Encontrar lugares de um tipo

O exemplo abaixo mostra uma solicitação do Nearby Search (New) para os nomes de exibição de todos os restaurantes em um raio de 500 metros, definido 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

Observe que o cabeçalho X-Goog-FieldMask especifica que a resposta contém os seguintes campos de dados: places.displayName. A resposta está 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, tipo e 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 vários tipos de lugares

O exemplo a seguir mostra uma solicitação do Nearby Search (New) para os nomes de exibição de todas as lojas de conveniência e de bebidas 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

Este exemplo adiciona 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 local apropriado nos resultados.

Excluir um tipo de lugar de uma pesquisa

O exemplo a seguir mostra uma solicitação do Nearby Search (New) 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, classificados por distância

O exemplo a seguir mostra uma solicitação do Nearby Search (New) para lugares próximos a 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!

Com a API Explorer, você pode fazer solicitações de amostra para conhecer a API e as opções dela.

Selecione o ícone da API, , no lado direito da página.
Se quiser, expanda Mostrar parâmetros padrão e defina o parâmetro fields como a máscara de campo.
Se quiser, 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 APIs Explorer, selecione o ícone de expansão para expandir a janela dele.

Pesquisa de local próximo (Novo)

Solicitações do Nearby Search (novas)

Respostas do Nearby Search (novo)

Parâmetros obrigatórios

FieldMask

locationRestriction

Parâmetros opcionais

includeTypes/excludedTypes, includedPrimaryTypes/excludedPrimaryTypes

includedTypes

excludedTypes

includedPrimaryTypes

excludedPrimaryTypes

languageCode

maxResultCount

rankPreference

regionCode