Pesquisa de local próximo (Novo)

Selecione a plataforma: Android iOS JavaScript Serviço da Web

Uma solicitação de Nearby Search (novo) usa um ou mais tipos de lugar e retorna uma lista de lugares correspondentes dentro da área especificada. Uma máscara de campo que especifica um ou mais tipos de dados é obrigatória. O Nearby Search (novo) só é compatível com solicitações POST.

Com o API Explorer, é possível fazer solicitações ativas para se familiarizar com a API e as opções de API:

Faça um teste

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 local 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 do 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 prática recomendada de design para garantir que você não solicite dados desnecessários. Isso ajuda a evitar cobranças desnecessárias no tempo de processamento e nas cobranças.

    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

    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.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, {19/2}, {18/2}, {2{/3/2}, {2, {2, {2places.nameplaces.subDestinationsplaces.typesplaces.utcOffsetMinutesplaces.viewport

      places/PLACE_ID Use places.displayName para acessar o texto do nome do lugar.

    • Os campos a seguir acionam a SKU do Nearby Search (Advanced):

      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.parkingOptions, places.parkingOptions, places.parkingOptionsplaces.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 deve estar entre 0,0 e 50.000,0, inclusive. O raio padrão é 0,0. Defina-o 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

  • allowedTypes/excludedTypes, includedPrimaryTypes/excludedPrimaryTypes

    Permite especificar uma lista de tipos dos tipos da 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 único tipo principal dos tipos da Tabela A associados a ele. Por exemplo, o tipo principal pode ser "mexican_restaurant" ou "steak_house". Use includedPrimaryTypes e excludedPrimaryTypes para filtrar os resultados com base 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", "establishment". Use includedTypes e excludedTypes para filtrar os resultados na lista de tipos associados a um lugar.

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

    includedTypes

    Uma lista separada por vírgulas dos tipos de lugares da Tabela A que devem ser 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 lugares 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 incluirá locais categorizados como "school", mas não como "primary_school". A resposta inclui locais que correspondem a pelo menos um dos includedTypes e nenhuma do excludedTypes.

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

    includedPrimaryTypes

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

    excludedPrimaryTypes

    Uma lista separada por vírgulas dos principais tipos de lugares da Tabela A para excluir 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 no qual os resultados serão retornados.

    • Veja 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 que seja legível para o usuário e os moradores. Para atingir esse objetivo, ele retorna endereços no idioma local, transliterado para um script legível pelo usuário, se necessário, observando o idioma preferido. Todos os outros endereços são retornados no idioma preferencial. Todos os componentes de endereço são 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.
    • O idioma preferido 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 lugar 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 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 da 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 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, 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 a seguir mostra uma solicitação do Nearby Search (novo) 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 estará, 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 Nearby Search (novo) para os nomes de exibição de todas as lojas de conveniência e lojas 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 local, facilitando a seleção do local apropriado nos resultados.

O exemplo a seguir mostra uma solicitação de Nearby Search (novo) 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 de Nearby Search (novo) para locais 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 o APIs Explorer, é possível fazer solicitações de amostra para se familiarizar com a API e as opções relacionadas.

  1. Selecione o ícone da API, Expanda o APIs Explorer., no lado direito da página.
  2. Se quiser, expanda Mostrar parâmetros padrão e defina o parâmetro fields como a máscara de campo.
  3. É possível editar o Corpo da solicitação.
  4. Selecione o botão Execute. 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 Expanda o APIs Explorer. para expandir a janela do API Explorer.