Pesquisa de local próximo (Novo)

Selecione a plataforma: Android iOS JavaScript Web Service

Uma Nearby Search (novo) request toma um ou mais tipos de locais e retorna uma lista de locais correspondentes dentro da na área especificada. Máscara de campo que especifica um ou mais tipos de dados. é obrigatório. O Nearby Search (novo) só é compatível com solicitações POST.

O APIs Explorer permite que você faça solicitações ativas para se familiarizar com a API e a Opções de API:

Faça um teste

Experimente a ferramenta demo 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 POST HTTP para um URL na formulário:

https://places.googleapis.com/v1/places:searchNearby

Transmita todos os parâmetros no corpo da solicitação JSON ou nos cabeçalhos como parte do 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 uma Place objeto. 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

    Especifique a lista de campos a serem retornados na resposta criando um máscara do campo de resposta. Transmita a máscara do campo de resposta ao 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 prática recomendada de design para garantir que você não solicite dados desnecessários, o que ajuda a evitar tempo de processamento desnecessário e cobranças de faturamento adicionais.

    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.attributions, 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.subDestinations, places.types, places.utcOffsetMinutes, places.viewport

      * O campo places.name contém o nome do recurso do lugar na forma: places/PLACE_ID. Usar o 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.servesBreakfast, places.servesBrunch, places.servesCocktails, places.servesCoffee, places.servesDessert, places.servesDinner, places.servesLunch, places.servesVegetarianFood, places.servesWine, places.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. Você deve defina-o na solicitação para 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 de tipos Tabela A usada para filtrar nos 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 Tabela A associada a reimplantá-lo. Por exemplo, o tipo principal pode ser "mexican_restaurant" ou "steak_house". Usar includedPrimaryTypes e excludedPrimaryTypes para filtrar os resultados o tipo principal de um lugar.

    Um lugar também pode ter vários valores de tipo de tipos. Tabela A associados a ele. Por exemplo, um restaurante pode ter os seguintes tipos: "seafood_restaurant", "restaurant" e "food". "point_of_interest", "establishment". Usar o includedTypes e excludedTypes para filtrar os resultados na lista de tipos associados a de um lugar.

    Quando você especifica um tipo principal geral, como "restaurant" ou "hotel", a resposta pode conter locais com um tipo principal mais específico do que o especificado. Por exemplo, você especifica a inclusão de um tipo primário de "restaurant": A resposta pode então conter locais com um tipo primário de "restaurant", mas a resposta também pode conter locais com um nome tipo primário, como "chinese_restaurant" ou "seafood_restaurant".

    Se uma pesquisa for especificada com várias restrições de tipo, apenas lugares que satisfaçam todas as restrições são retornadas. Por exemplo, se você especificar {"includedTypes": ["restaurant"], "excludedPrimaryTypes": ["steak_house"]}, o Os lugares retornados oferecem serviços relacionados a "restaurant", mas não funcionam 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 lugar da Tabela A para excluir de uma pesquisa.

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

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

    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 includedPrimaryTypes e excludedPrimaryTypes, uma INVALID_ARGUMENT será retornado.

  • languageCode

    O idioma no qual os resultados serão retornados.

    • Veja a lista de idiomas compatíveis. Google com frequência atualiza os idiomas compatíveis, portanto, esta 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 erro.
    • A API faz o possível para fornecer um endereço que seja legível tanto para o usuário quanto para dos habitantes locais. 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 método idioma de destino. 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 preferido tem uma pequena influência no conjunto de resultados que a API escolhe e a ordem em que foram devolvidos. O geocodificador interpreta abreviações de maneira diferente dependendo do idioma, como abreviações de tipos de ruas 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 em um local específico.

  • regionCode

    O código da região usado para formatar a resposta, especificado como um 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 é omitido de formattedAddress. Esse parâmetro não tem efeito sobre adrFormatAddress, que sempre inclui o país nome, ou em shortFormattedAddress, que nunca o inclui.

    A maioria dos códigos CLDR é idêntica 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 os "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 de Nearby Search (novo) para a tela. 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 estará 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 do restaurante, tipo e endereço da Web 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 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
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 dos 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 perto de um ponto no centro de São Francisco. Neste exemplo, você inclui 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, você pode fazer solicitações de amostra para se familiarizar com a API e as opções de API.

  1. Selecione o ícone da API, Expanda o APIs Explorer., no lado direito da página.
  2. Como opção, expanda Mostrar parâmetros padrão e defina O parâmetro fields à 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 APIs Explorer, selecione o ícone de expansão, Expanda o APIs Explorer. para expandir a janela do APIs Explorer.