Esta página foi traduzida pela API Cloud Translation.

Nearby Search (novo)
Mantenha tudo organizado com as coleções Salve e categorize o conteúdo com base nas suas preferências.

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 por proximidade (nova) só aceita solicitações POST.

O APIs 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 ver os resultados da Pesquisa por proximidade (nova) exibidos em um mapa.

Solicitações do Nearby Search (novo)

Uma solicitação de pesquisa por proximidade (nova) é 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)

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 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 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
```
Observação : não é permitido usar espaços em nenhum lugar da lista de campos.

Use * para recuperar todos os campos.
```
X-Goog-FieldMask: *
```
O caractere curinga "*" seleciona todos os campos. No entanto, embora esse curinga possa ser usado no desenvolvimento, o Google desencoraja o uso da máscara de campo de resposta curinga (*) na produção devido à grande quantidade de dados que podem ser retornados.

Outras orientações para usar places.iconMaskBaseUri e places.iconBackgroundColor podem ser encontradas na seção Ícones de lugar.

Especifique um ou mais dos seguintes campos:
- Os campos a seguir acionam a SKU do Nearby Search Pro:
  
  places.accessibilityOptions
  places.addressComponents
  places.addressDescriptor^*
  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.postalAddress
  places.primaryType
  places.primaryTypeDisplayName
  places.pureServiceAreaBusiness
  places.shortFormattedAddress
  places.subDestinations
  places.types
  places.utcOffsetMinutes
  places.viewport
  
  ^* Os descritores de endereço geralmente estão disponíveis para clientes na Índia e são experimentais em outros lugares.
  
  ^** O campo places.googleMapsLinks está na fase de pré-lançamento da visualização e não há cobrança. Isso significa que o faturamento é de US $0,00 para o uso durante a visualização.
  
  ^*** 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 da Pesquisa empresarial do Google:
  
  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 a SKU Nearby Search Enterprise + Atmosphere:
  
  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 a Pesquisa de texto e a Pesquisa por perto
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. É necessário 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.

Observação : os valores na Tabela B são retornados apenas na resposta. Não é possível usar valores na Tabela B como um filtro.

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

Se você omitir includedTypes, excludedTypes, includedPrimaryTypes e excludedPrimaryTypes da solicitação, a pesquisa vai retornar lugares de todos os tipos dentro dos limites de restrição de local.

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 com frequência os idiomas compatíveis, então 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 que seja legível para o usuário e para os moradores. Para isso, ele retorna endereços no idioma local, transliterados para uma escrita legível pelo usuário, se necessário, observando o idioma preferido. Todos os outros endereços são retornados no idioma preferencial. Os componentes do endereço são todos retornados no mesmo idioma, que é escolhido a partir do primeiro componente.
- Se um nome não estiver disponível no idioma preferencial, a API usará a correspondência mais próxima.
- A linguagem preferencial tem uma pequena influência no conjunto de resultados que a API escolhe retornar e na ordem em que eles são retornados. 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), 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 pela 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 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), e 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 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 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.

Excluir um tipo de lugar de uma pesquisa

O exemplo a seguir mostra uma solicitação de pesquisa nas 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

Conferir descritores de endereço

Os descritores de endereço fornecem informações relacionais sobre o local de um lugar, incluindo pontos de referência próximos e áreas que o contêm.

Observação:os descritores de endereço geralmente estão disponíveis para clientes na Índia e são experimentais em outros lugares. As solicitações da API Places que usam apenas addressDescriptor na máscara de campo serão faturadas em SKU: Places API Nearby Search Pro.

O exemplo a seguir mostra uma solicitação de pesquisa por proximidades (nova) para lugares perto de um shopping em San José. Neste exemplo, você inclui addressDescriptors na máscara de campo:

curl -X POST -d '{
  "maxResultCount": 5,
  "locationRestriction": {
    "circle": {
      "center": {
        "latitude": 37.321328,
        "longitude": -121.946275
      },"radius": 1000
    }
  },
  "includedTypes": ["restaurant", "cafe"],
  "excludedTypes": [],
  "rankPreference":"POPULARITY"
}' \
-H 'Content-Type: application/json' \
-H "X-Goog-Api-Key: API_KEY" \
-H "X-Goog-FieldMask: places.displayName,places.addressDescriptor" \
https://places.googleapis.com/v1/places:searchNearby

A resposta inclui o lugar especificado na solicitação, uma lista de pontos de referência próximos e a distância deles até o lugar, além de uma lista de áreas e a relação de contenção delas com o lugar:

  {
    "places": [
      {
        "displayName": {
          "text": "Westfield Valley Fair",
          "languageCode": "en"
        },
        "addressDescriptor": {
          "landmarks": [
            {
              "name": "places/ChIJ62_oCR7Lj4AR_MGWkSPotD4",
              "placeId": "ChIJ62_oCR7Lj4AR_MGWkSPotD4",
              "displayName": {
                "text": "Nordstrom",
                "languageCode": "en"
              },
              "types": [
                "clothing_store",
                "department_store",
                "establishment",
                "point_of_interest",
                "shoe_store",
                "store"
              ],
              "straightLineDistanceMeters": 114.76984,
              "travelDistanceMeters": 114.261856
            },
            {
              "name": "places/ChIJgexMlR_Lj4ARiKCKuhNnjn0",
              "placeId": "ChIJgexMlR_Lj4ARiKCKuhNnjn0",
              "displayName": {
                "text": "Valley Fair Mall Eyexam of CA",
                "languageCode": "en"
              },
              "types": [
                "establishment",
                "health",
                "point_of_interest"
              ],
              "straightLineDistanceMeters": 131.62566,
              "travelDistanceMeters": 237.33253
            },
            {
              "name": "places/ChIJWWIlNx7Lj4ARpe1E0ob-_GI",
              "placeId": "ChIJWWIlNx7Lj4ARpe1E0ob-_GI",
              "displayName": {
                "text": "Din Tai Fung",
                "languageCode": "en"
              },
              "types": [
                "establishment",
                "food",
                "point_of_interest",
                "restaurant"
              ],
              "straightLineDistanceMeters": 110.0775,
              "travelDistanceMeters": 171.41951
            },
            {
              "name": "places/ChIJwyfPQx7Lj4AR7bYI2A2Yc54",
              "placeId": "ChIJwyfPQx7Lj4AR7bYI2A2Yc54",
              "displayName": {
                "text": "Abercrombie & Fitch",
                "languageCode": "en"
              },
              "types": [
                "clothing_store",
                "establishment",
                "point_of_interest",
                "shoe_store",
                "store"
              ],
              "spatialRelationship": "DOWN_THE_ROAD",
              "straightLineDistanceMeters": 53.620117,
              "travelDistanceMeters": 2.4578214
            },
            {
              "name": "places/ChIJpycNQx7Lj4ARjhXw3PrM_kU",
              "placeId": "ChIJpycNQx7Lj4ARjhXw3PrM_kU",
              "displayName": {
                "text": "Hollister Co.",
                "languageCode": "en"
              },
              "types": [
                "clothing_store",
                "establishment",
                "point_of_interest",
                "shoe_store",
                "store"
              ],
              "spatialRelationship": "DOWN_THE_ROAD",
              "straightLineDistanceMeters": 56.53726,
              "travelDistanceMeters": 15.418246
            }
          ],
          "areas": [
            {
              "name": "places/ChIJb3F-EB7Lj4ARnHApQ_Hu1gI",
              "placeId": "ChIJb3F-EB7Lj4ARnHApQ_Hu1gI",
              "displayName": {
                "text": "Westfield Valley Fair",
                "languageCode": "en"
              },
              "containment": "WITHIN"
            },
            {
              "name": "places/ChIJXYuykB_Lj4AR1Ot8nU5q26Q",
              "placeId": "ChIJXYuykB_Lj4AR1Ot8nU5q26Q",
              "displayName": {
                "text": "Valley Fair",
                "languageCode": "en"
              },
              "containment": "WITHIN"
            },
            {
              "name": "places/ChIJtYoUX2DLj4ARKoKOb1G0CpM",
              "placeId": "ChIJtYoUX2DLj4ARKoKOb1G0CpM",
              "displayName": {
                "text": "Central San Jose",
                "languageCode": "en"
              },
              "containment": "OUTSKIRTS"
            }
          ]
        }
      },
  /.../
  }

Confira!

O APIs Explorer permite fazer solicitações de amostra para que você se familiarize com a API e as opções dela.

Selecione o ícone da API api no lado direito da página.
Edite os parâmetros de solicitação, se quiser.
Selecione o botão Executar. Na caixa de diálogo, escolha a conta que você quer usar para fazer a solicitação.
No painel do APIs Explorer, selecione o ícone de tela cheia fullscreen para expandir a janela do APIs Explorer.

Nearby Search (novo) Mantenha tudo organizado com as coleções Salve e categorize o conteúdo com base nas suas preferências.

Solicitações do Nearby Search (novo)

Respostas do Nearby Search (novo)

Parâmetros obrigatórios

FieldMask

locationRestriction

Parâmetros opcionais

includedTypes/excludedTypes, includedPrimaryTypes/excludedPrimaryTypes

includedTypes

excludedTypes

includedPrimaryTypes

excludedPrimaryTypes

languageCode

maxResultCount

rankPreference

regionCode