Pesquisa de local próximo (Novo)

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 Nearby Search (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:

Use a demonstração interativa para ver os resultados do Nearby Search (novo) exibidos em um mapa.

Solicitações do Nearby Search (novo)

Uma solicitação de Nearby Search (novo) é 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 Nearby Search (novo) 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 está no formato:

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

Parâmetros obrigatórios

• FieldMask

  Crie uma máscara de campo de resposta para especificar a lista de campos a serem retornados na 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 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

  Use * para recuperar todos os campos.

  X-Goog-FieldMask: *

  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.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 deve estar entre 0,0 e 50.000,0, inclusive. 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

• allowedTypes/excludedTypes, includedPrimaryTypes/excludedPrimaryTypes

  Permite especificar uma lista de tipos de Tabela A usados para filtrar os resultados da pesquisa. Até 50 tipos podem ser especificados em cada categoria de restrição.

  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 locais com um tipo principal de "restaurant", mas também pode conter locais 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".

  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 algum tipo principal conflitante, 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 compatíveis com frequência. Por isso, essa 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 que seja legível para o usuário e os moradores. 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 uma das seguintes opções:

  • POPULARITY (padrão) Classifica os resultados com base na popularidade.
  • DISTANCE Classifica os resultados em ordem crescente de distância do local especificado.

• 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 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, 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 por proximidades (nova) para os nomes de exibição de todas as lojas de conveniência e de 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

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.

1. Selecione o ícone da API, , no lado direito da página.
2. Opcionalmente, abra Mostrar parâmetros padrão e defina o parâmetro fields para a máscara de campo.
3. É possível editar o Corpo da solicitação.
4. Selecione o botão Executar. No pop-up, escolha a conta que você quer usar para fazer a solicitação.

5. No painel do API Explorer, selecione o ícone de expansão para expandir a janela do API Explorer.