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

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

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

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

    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.

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.

  1. Se quiser, expanda Mostrar parâmetros padrão e defina o parâmetro fields como a máscara de campo.
  2. Se quiser, edite o Corpo da solicitação.
  3. Selecione o botão Executar. No pop-up, escolha a conta que você quer usar para fazer a solicitação.