Find Place (legado)

Uma solicitação do Find Place (legado) recebe uma entrada de texto e retorna um lugar. A entrada pode ser qualquer tipo de dados de texto do Places, como nome, endereço ou número de telefone. A solicitação precisa ser uma string. Uma solicitação do Find Place (legado) que usa dados que não são strings, como uma coordenada de latitude/longitude ou um Plus Code, gera um erro.

Solicitações do Find Place (legado)

Uma solicitação do Find Place (legado) é um URL HTTP no seguinte formato:

https://maps.googleapis.com/maps/api/place/findplacefromtext/output?parameters

em que output pode ser um dos seguintes valores:

• json (recomendado) indica a saída em JavaScript Object Notation (JSON)
• xml indica a saída como XML.

Alguns parâmetros são obrigatórios para iniciar uma solicitação do Find Place (legado). Como é padrão em URLs, todos os parâmetros são separados usando o caractere E comercial (&).

Parâmetros obrigatórios

• entrada

  A string de texto em que a pesquisa será feita. Precisa ser o nome, endereço ou número de telefone de um lugar (por exemplo, "Rua Principal, 123" ou "Prefeitura").

• inputtype

  O tipo de entrada. Pode ser textquery ou phonenumber. Os números de telefone precisam estar no formato internacional (com um sinal de adição "+" como prefixo, seguido pelo código do país e telefone. Consulte a recomendação E.164 ITU para mais informações.

Parâmetros opcionais

• campos

  Atenção:as solicitações do Place Search (Legacy) e do Place Details (Legacy) não retornam os mesmos campos. As solicitações do Place Search (legado) retornam um subconjunto dos campos retornados pelas solicitações do Place Details (legado). Se o campo que você quer não for retornado pelo Place Search (legado), use o Place Search (legado) para receber um place_id e use esse ID de lugar para fazer uma solicitação do Place Details (legado). Para mais informações sobre os campos que não estão disponíveis em uma solicitação do Place Search (Legacy), consulte Suporte a campos da API Places.

  Use o parâmetro fields para especificar uma lista separada por vírgulas de tipos de dados de lugar a serem retornados. (por exemplo: fields=formatted_address,name,geometry). Use uma barra ao especificar valores compostos. Por exemplo, opening_hours/open_now.

  Os campos são divididos em três categorias de faturamento: Basic, Contact e Atmosphere. Os campos Basic são faturados na taxa básica, e os campos Contact e Atmosphere são faturados em uma taxa maior. As SKUs Basic, Contact e Atmosphere são cobradas além da SKU base (Places Details, Find Place, Nearby Search ou Text Search) da solicitação que as acionou. Para mais informações, consulte a tabela de preços.

  Basic

  A categoria "Basic" inclui os seguintes campos: address_components, adr_address, business_status, formatted_address, geometry, icon, icon_mask_base_uri, icon_background_color, name, permanently_closed (descontinuado), photo, place_id, plus_code, type, url, utc_offset, vicinity, wheelchair_accessible_entrance.

  Contato

  A categoria "Contact" inclui os seguintes campos: current_opening_hours, formatted_phone_number, international_phone_number, opening_hours, secondary_opening_hours, website

  Atmosphere

  A categoria "Atmosphere" inclui os seguintes campos: curbside_pickup, delivery, dine_in, editorial_summary, price_level, rating, reservable, reviews, serves_beer, serves_breakfast, serves_brunch, serves_dinner, serves_lunch, serves_vegetarian_food, serves_wine, takeout, user_ratings_total.

  Observação:as atribuições, html_attributions, são sempre retornadas a cada chamada, independentemente de o campo ter sido solicitado.

• language

  O idioma em que os resultados serão retornados.

  • Consulte a lista de idiomas compatíveis. O Google atualiza os idiomas compatíveis com frequência, então esta lista pode não estar completa.
  • Se language não for fornecido, a API vai tentar usar o idioma preferencial, conforme especificado no cabeçalho Accept-Language.
  • A API faz o possível para fornecer um endereço que seja legível para o usuário e os moradores locais. Para isso, ele retorna endereços no idioma local, transliterados para um script legível pelo usuário, se necessário, de acordo com 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, que é escolhido no primeiro componente.
  • Se um nome não estiver disponível no idioma preferido, a API vai usar a correspondência mais próxima.
  • O idioma 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 as abreviações de tipos de rua ou sinônimos que podem ser válidos em um idioma, mas não em outro. Por exemplo, utca e tér são sinônimos de rua em húngaro.

• locationbias

  Prioriza resultados em uma área específica, definindo um raio mais latitude/longitude ou dois pares de latitude/longitude que representam os pontos de um retângulo. Se esse parâmetro não for especificado, a API vai usar o viés de endereço IP por padrão.

  • Viés de IP: instrui a API a usar o viés de endereço IP. Transmita a string ipbias (essa opção não tem parâmetros adicionais).
  • Circular: uma string que especifica o raio em metros, além de latitude/longitude em graus decimais. Use o seguinte formato: circle:radius@lat,lng.
  • Retangular: uma string que especifica dois pares de latitude/longitude em graus decimais, representando os pontos sul/oeste e norte/leste de um retângulo. Use o seguinte formato:rectangle:south,west|north,east. Os valores leste/oeste são ajustados para o intervalo de -180 a 180, e os valores norte/sul são fixados no intervalo de -90 a 90.

Exemplos de Find Place (legado)

O exemplo a seguir mostra uma solicitação do Find Place (legado) para "Museu de Arte Contemporânea da Austrália", incluindo os campos photos, formatted_address, name, rating, opening_hours e geometry:

curl -L -X GET 'https://maps.googleapis.com/maps/api/place/findplacefromtext/json?input=Museum%20of%20Contemporary%20Art%20Australia&inputtype=textquery&fields=formatted_address%2Cname%2Crating%2Copening_hours%2Cgeometry&key=YOUR_API_KEY'

https://maps.googleapis.com/maps/api/place/findplacefromtext/json
    ?fields=formatted_address%2Cname%2Crating%2Copening_hours%2Cgeometry
    &input=Museum%20of%20Contemporary%20Art%20Australia
    &inputtype=textquery
    &key=YOUR_API_KEY

O exemplo a seguir mostra uma solicitação do Find Place (Legacy) para "Mongolian Grill", usando o parâmetro locationbias para priorizar resultados em um raio de 2.000 metros das coordenadas especificadas:

curl -L -X GET 'https://maps.googleapis.com/maps/api/place/findplacefromtext/json?input=Mongolian%20Grill&inputtype=textquery&fields=formatted_address%2Cname%2Crating%2Copening_hours%2Cgeometry&locationbias=circle:2000@−33.866,151.216&key=YOUR_API_KEY'

https://maps.googleapis.com/maps/api/place/findplacefromtext/json
    ?fields=formatted_address%2Cname%2Crating%2Copening_hours%2Cgeometry
    &input=Mongolian%20Grill
    &inputtype=textquery
    &locationbias=circle:2000@−33.866,151.216
    &key=YOUR_API_KEY

O exemplo a seguir mostra uma solicitação do Find Place (Legacy) para um número de telefone. O prefixo de chamada internacional "+" foi codificado como %2B para que essa solicitação seja um URL compatível. Se não for codificado, o prefixo + será decodificado como um espaço no servidor, resultando em uma pesquisa de número de telefone inválida.

curl -L -X GET 'https://maps.googleapis.com/maps/api/place/findplacefromtext/json?input=%2B16502530000&inputtype=phonenumber&fields=formatted_address%2Cname%2Crating%2Copening_hours%2Cgeometry&key=YOUR_API_KEY'

https://maps.googleapis.com/maps/api/place/findplacefromtext/json
    ?fields=formatted_address%2Cname%2Crating%2Copening_hours%2Cgeometry
    &input=%2B16502530000
    &inputtype=phonenumber
    &key=YOUR_API_KEY

Respostas do Find Place (legado)

Uma resposta do Find Place (legado) contém apenas os tipos de dados especificados usando o parâmetro fields, além de html_attributions. O exemplo a seguir mostra a resposta a uma solicitação do Find Place (legado) para "Museu de Arte Contemporânea da Austrália", incluindo os campos formatted_address, geometry, name, opening_hours, photos e rating.

{
  "candidates":
    [
      {
        "formatted_address": "140 George St, The Rocks NSW 2000, Australia",
        "geometry":
          {
            "location": { "lat": -33.8599358, "lng": 151.2090295 },
            "viewport":
              {
                "northeast":
                  { "lat": -33.85824377010728, "lng": 151.2104386798927 },
                "southwest":
                  { "lat": -33.86094342989272, "lng": 151.2077390201073 },
              },
          },
        "name": "Museum of Contemporary Art Australia",
        "opening_hours": { "open_now": false },
        "rating": 4.4,
      },
    ],
  "status": "OK",
}    

<?xml version="1.0" encoding="UTF-8"?>
<FindPlaceFromTextResponse>
 <candidates>
  <name>Museum of Contemporary Art Australia</name>
  <formatted_address>140 George St, The Rocks NSW 2000, Australia</formatted_address>
  <geometry>
   <location>
    <lat>-33.8599358</lat>
    <lng>151.2090295</lng>
   </location>
   <viewport>
    <southwest>
     <lat>-33.8609434</lat>
     <lng>151.2077390</lng>
    </southwest>
    <northeast>
     <lat>-33.8582438</lat>
     <lng>151.2104387</lng>
    </northeast>
   </viewport>
  </geometry>
  <rating>4.4</rating>
  <opening_hours>
   <open_now>false</open_now>
  </opening_hours>
 </candidates>
 <status>OK</status>
</FindPlaceFromTextResponse>

    

PlacesFindPlaceFromTextResponse

PlacesSearchStatus

Códigos de status retornados pelo serviço.

• OK: indicando que a solicitação de API funcionou.
• ZERO_RESULTS, indicando que a pesquisa foi bem-sucedida, mas não retornou resultados. Isso pode ocorrer se a pesquisa recebeu um latlng em um local remoto.
• INVALID_REQUEST: indicando que a solicitação de API estava corrompida, geralmente devido à falta de um parâmetro de consulta obrigatório (location ou radius).
• OVER_QUERY_LIMIT indicando qualquer uma das seguintes opções:
  • Você excedeu os limites de QPS.
  • O faturamento não foi ativado na sua conta.
  • O crédito mensal de US $200 ou um limite de uso definido pelo próprio usuário foi excedido.
  • A forma de pagamento fornecida não é mais válida (por exemplo, o cartão de crédito expirou).
  Consulte as perguntas frequentes do Maps para mais informações sobre como resolver esse erro.
• REQUEST_DENIED indica que o pedido foi recusado, geralmente porque:
  • A solicitação não tem uma chave de API.
  • O parâmetro key é inválido.
• UNKNOWN_ERROR: indicando um erro desconhecido.

Lugar

As respostas do Place Search retornam o seguinte subconjunto de campos de Place. Nem todos os atributos estão disponíveis para todos os tipos de lugar. Para recuperar campos que o Place Search não retorna, como address_components, formatted_phone_number, reviews ou website, transmita o place_id retornado em uma solicitação do Place Details (Legacy). Para saber mais sobre a disponibilidade de campos e os níveis de preços em endpoints, consulte Campos de dados de lugar (legado).