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

    Use * para recuperar todos os campos.

    X-Goog-FieldMask: *

    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.

    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".

    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.

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, Abra o API Explorer., 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. Se preferir, edite 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, Abra o API Explorer., para abrir a janela do API Explorer.