Preenchimento automático (novo)

O Autocomplete (novo) é um serviço da Web que retorna sugestões de lugares e consultas em resposta a uma solicitação HTTP. Na solicitação, especifique uma string de pesquisa de texto e limites geográficos que controlem a área de pesquisa.

O serviço Autocomplete (novo) pode fazer correspondências com palavras completas e substrings da entrada, resolvendo nomes, endereços e Plus Codes de lugares. À medida que a pessoa digita, os aplicativos enviam consultas e sugerem previsões de local e consulta instantaneamente.

A resposta da API Autocomplete (nova) pode conter dois tipos de previsões:

  • Previsões de lugares: lugares, como empresas, endereços e pontos de interesse, com base na string de texto de entrada e na área de pesquisa especificadas. As previsões de lugares são retornadas por padrão.
  • Previsões de consulta: strings de consulta que correspondem à string de texto de entrada e à área de pesquisa. As previsões de consulta não são retornadas por padrão. Use o parâmetro de solicitação includeQueryPredictions para adicionar previsões de consulta à resposta.

Por exemplo, você chama a API usando como entrada uma string que contém uma entrada parcial do usuário, "piz siciliano", com a área de pesquisa limitada a São Francisco, CA. A resposta contém uma lista de previsões de lugar que correspondem à string de pesquisa e à área de pesquisa, como o restaurante chamado "Sicilian Pizza Kitchen", além de detalhes sobre o lugar.

As previsões de lugar retornadas são apresentadas ao usuário para ajudar na escolha do lugar que você quer. Você pode fazer uma solicitação Place Details (novo) para receber mais informações sobre qualquer uma das previsões de lugar retornadas.

A resposta também pode conter uma lista de previsões de consulta que correspondem à string de pesquisa e à área de pesquisa, como "Sicilian Pizza & Pasta". Cada previsão de consulta na resposta inclui o campo text que contém uma string de pesquisa de texto recomendada. Use essa string como entrada para a Pesquisa de texto (novo) para realizar uma pesquisa mais detalhada.

Solicitações de Autocomplete (novas)

Uma solicitação de Autocomplete (nova) é uma solicitação HTTP POST para um URL no formato:

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

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 '{
  "input": "pizza",
  "locationBias": {
    "circle": {
      "center": {
        "latitude": 37.7937,
        "longitude": -122.3965
      },
      "radius": 500.0
    }
  }
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
https://places.googleapis.com/v1/places:autocomplete

Fazer uma solicitação usando o Autocomplete (novo)

A API Places é compatível com as APIs Autocomplete e Query Autocomplete. Se você já conhece essas APIs, a versão de pré-lançamento do Autocomplete (novo) faz as seguintes mudanças:

  • O novo preenchimento automático usa solicitações POST HTTP. Transmita parâmetros no corpo da solicitação ou nos cabeçalhos como parte de uma solicitação HTTP POST. Por outro lado, com as APIs atuais, você transmite parâmetros de URL usando uma solicitação HTTP GET.
  • O novo preenchimento automático oferece suporte a chaves de API e tokens do OAuth como mecanismo de autenticação.
  • Apenas JSON é compatível como formato de resposta no novo preenchimento automático.

A tabela a seguir lista os parâmetros nas APIs Autocomplete e Query Autocomplete que foram renomeadas ou modificadas para o novo Autocomplete ou que não são mais compatíveis.

Parâmetro atual Novo parâmetro Observações
components includedRegionCodes
language languageCode
location locationBias
ipbias Se você omitir locationBias e locationRestriction, a API usará a polarização de IP por padrão.
offset inputOffset
radius locationBias ou locationRestriction
region regionCode
stricbounds locationRestriction
sessiontoken sessionToken
types includedPrimaryTypes

Limites de uso

Durante a versão de pré-lançamento, você tem o limite de fazer 600 consultas por minuto em cada projeto.

Opções de suporte para versões de pré-lançamento

Embora o Google não tenha a obrigação de oferecer suporte às versões de pré-lançamento, aos recursos ou às funcionalidades dos Serviços, vamos considerar as solicitações nessas etapas de desenvolvimento caso a caso.

  • As versões de pré-lançamento não são cobertas pelo SLA da Plataforma Google Maps.
  • É recomendável usar mecanismos substitutos, especialmente se você estiver usando uma versão de pré-lançamento em um ambiente de produção. Alguns exemplos de situações de substituição são: cota excedida, latência e códigos de respostas inesperados ou respostas inesperadas em comparação com o Autocomplete atual.

Você pode usar o Issue Tracker para solicitar novos recursos ou sugerir modificações aos atuais. Descreva a funcionalidade específica que você gostaria que fosse adicionada e por que você a acha importante. Se possível, inclua detalhes específicos sobre seu caso de uso e as novas oportunidades que o recurso permitiria:

Para qualquer outra dúvida sobre recursos, envie um e-mail para newplacesapi@google.com.

Sobre a resposta

O preenchimento automático (novo) retorna um objeto JSON como resposta. Na resposta:

  • A matriz suggestions contém todos os lugares e consultas previstos em ordem com base na relevância percebida. Cada lugar é representado por um campo placePrediction, e cada consulta é representada por um campo queryPrediction.
  • Um campo placePrediction contém informações detalhadas sobre uma única previsão de lugar, incluindo o ID do lugar e a descrição em texto.
  • Um campo queryPrediction contém informações detalhadas sobre uma única previsão de consulta.

O objeto JSON completo está no formato:

{
  "suggestions": [
    {
      "placePrediction": {
        "place": "places/ChIJ5YQQf1GHhYARPKG7WLIaOko",
        "placeId": "ChIJ5YQQf1GHhYARPKG7WLIaOko",
        "text": {
          "text": "Amoeba Music, Haight Street, San Francisco, CA, USA",
          "matches": [
            {
              "endOffset": 6
            }]
        },
      ...
    },
    {
      "queryPrediction": {
        "text": {
          "text": "Amoeba Music",
          "matches": [
            {
              "endOffset": 6
            }]
        },
        ...
    }
  ...]
}

Parâmetros obrigatórios

  • entrada

    A string de texto na qual pesquisar. Especifique palavras completas e substrings, nomes de lugares, endereços e Plus Codes. O serviço Autocomplete (novo) retorna correspondências possíveis de acordo com essa string e ordena os resultados com base na relevância.

Parâmetros opcionais

  • includedPrimaryTypes

    Um local só pode ter um único tipo principal dos tipos Tabela A ou Tabela B associadas a ele. Por exemplo, o tipo principal pode ser "mexican_restaurant" ou "steak_house".

    Por padrão, a API retorna todos os lugares com base no parâmetro input, independentemente do valor do tipo principal associado ao lugar. Para restringir os resultados a um determinado tipo principal ou principal, transmita o parâmetro includedPrimaryTypes.

    Use esse parâmetro para especificar até cinco valores de tipo da tabela A ou tabela B. Um local precisa corresponder a um dos valores de tipo principal especificados para ser incluído na resposta.

    A solicitação será rejeitada com um erro INVALID_REQUEST se:

    • Mais de cinco tipos foram especificados.
    • Todos os tipos não reconhecidos foram especificados.

  • includeQueryPredictions

    Se for true, a resposta incluirá previsões de local e consulta. O valor padrão é false, o que significa que a resposta inclui apenas previsões de local.

  • includedRegionCodes

    Inclua apenas resultados da lista de regiões especificadas, especificadas como uma matriz de até 15 valores de ccTLD ("domínio de nível superior") de dois caracteres. Se omitida, nenhuma restrição será aplicada à resposta. Por exemplo, para limitar as regiões à Alemanha e à França:

        "includedRegionCodes": ["de", "fr"]

    Se você especificar locationRestriction e includedRegionCodes, os resultados ficarão localizados na área de interseção das duas configurações.

  • inputOffset

    O deslocamento de caractere Unicode baseado em zero que indica a posição do cursor em input. A posição do cursor pode influenciar quais previsões são retornadas. Se estiver vazio, o padrão será o comprimento de input.

  • languageCode

    O idioma preferido no qual os resultados serão retornados. Os resultados poderão aparecer em idiomas mistos se o idioma usado no input for diferente do valor especificado por languageCode ou se o local retornado não tiver uma tradução do idioma local para languageCode.

    • Use os códigos de idioma IETF BCP-47 para especificar o idioma de preferência.
    • Se languageCode não for fornecido, a API usará o valor especificado no cabeçalho Accept-Language. Se nenhum deles for especificado, o padrão será en. Se você especificar um código de idioma inválido, a API retornará um erro INVALID_ARGUMENT.
    • O idioma preferencial tem uma pequena influência no conjunto de resultados que a API escolhe retornar e na ordem em que são retornados. Isso também afeta a capacidade da API de corrigir erros de ortografia.
    • A API tenta fornecer um endereço legível para o usuário e para a população local, ao mesmo tempo que reflete a entrada do usuário. As previsões de lugar são formatadas de forma diferente, dependendo da entrada do usuário em cada solicitação.
      • Os termos correspondentes no parâmetro input são escolhidos primeiro, usando nomes alinhados com a preferência de idioma indicada pelo parâmetro languageCode, quando disponível. Caso contrário, usam os nomes que melhor correspondem à entrada do usuário.
      • Os endereços são formatados no idioma local em um script que pode ser lido pelo usuário quando possível, somente depois que os termos correspondentes forem escolhidos para corresponder aos termos no parâmetro input.
      • Todos os outros endereços são retornados no idioma preferencial, depois que os termos correspondentes forem escolhidos para corresponder aos termos no parâmetro input. Se um nome não estiver disponível no idioma preferencial, a API usará a correspondência mais próxima.

  • locationBias ou locationRestriction

    Você pode especificar locationBias ou locationRestriction, mas não ambos, para definir a área de pesquisa. Pense em locationRestriction como uma especificação da região em que os resultados precisam estar, e locationBias como uma região em que os resultados precisam estar próximos, mas que podem estar fora da área.

    • locationBias

      Especifica uma área a ser pesquisada. Esse local serve como um viés, o que significa que resultados no local especificado podem ser retornados, incluindo resultados fora da área especificada.

    • locationRestriction

      Especifica uma área a ser pesquisada. Os resultados fora da área especificada não são retornados.

    Especifique a região locationBias ou locationRestriction como uma janela de visualização retangular ou como um círculo.

    • Um círculo é definido 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. Para locationRestriction, é necessário definir o raio com um valor maior que 0,0. Caso contrário, a solicitação não retornará resultados.

      Exemplo:

      "locationBias": {
  "circle": {
    "center": {
      "latitude": 37.7937,
      "longitude": -122.3965
    },
    "radius": 500.0
  }
}

    • Um retângulo é uma janela de visualização de latitude e longitude, representada como duas low diagonalmente opostos e pontos altos. Uma janela de visualização é considerada uma região fechada, ou seja, que inclui o limite dela. Os limites de latitude precisam variar de -90 a 90 graus, e os limites de longitude precisam variar de -180 a 180 graus:

      • Se low = high, a janela de visualização consiste nesse único ponto.
      • Se low.longitude > high.longitude, o intervalo de longitude será invertido (a janela de visualização cruza a linha de longitude de 180 graus).
      • Se low.longitude = -180 graus e high.longitude = 180 graus, a janela de visualização incluirá todas as longitudes.
      • Se low.longitude = 180 graus e high.longitude = -180 graus, o intervalo de longitude ficará vazio.

      Preencha low e high, e a caixa representada não pode ficar vazia. Uma janela de visualização vazia resulta em erro.

      Por exemplo, esta janela de visualização abrange totalmente a cidade de Nova York:

      "locationBias": {
  "rectangle": {
    "low": {
      "latitude": 40.477398,
      "longitude": -74.259087
    },
    "high": {
      "latitude": 40.91618,
      "longitude": -73.70018
    }
  }
}

  • origem

    O ponto de origem a partir do qual calcular a distância em linha reta até o destino (retornado como distanceMeters). Se esse valor for omitido, a distância em linha reta não será retornada. Precisa ser especificado como coordenadas de latitude e longitude:

    "origin": {
    "latitude": 40.477398,
    "longitude": -74.259087
}

  • regionCode

    O código regional usado para formatar a resposta, especificado como um valor de dois caracteres ccTLD ("domínio de nível superior"). A maioria dos códigos ccTLD é 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").

    Se você especificar um código de região inválido, a API retornará um erro INVALID_ARGUMENT. O parâmetro pode afetar os resultados com base na legislação aplicável.

  • sessionToken

    Os tokens de sessão são strings geradas pelo usuário que rastreiam chamadas de preenchimento automático (novas) como "sessões". O Autocomplete (novo) usa tokens de sessão para agrupar as fases de consulta e seleção de uma pesquisa de preenchimento automático do usuário em uma sessão discreta para fins de faturamento. Para mais informações, consulte Tokens de sessão.

Exemplos de preenchimento automático (novo)

Usar locationRestriction e locationBias

A API usa a polarização de IP por padrão para controlar a área de pesquisa. Com o direcionamento de IP, a API usa o endereço IP do dispositivo para direcionar os resultados. Opcionalmente, você pode usar locationRestriction ou locationBias, mas não ambos, para especificar uma área a ser pesquisada.

locationRestriction especifica a área a ser pesquisada. Os resultados fora da área especificada não são retornados. No exemplo a seguir, use locationRestriction para limitar a solicitação a um círculo de 5.000 metros em um raio centralizado em São Francisco:

curl -X POST -d '{
  "input": "Amoeba",
  "locationRestriction": {
    "circle": {
      "center": {
        "latitude": 37.7749,
        "longitude": -122.4194
      },
      "radius": 5000.0
    }
  }
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
https://places.googleapis.com/v1/places:autocomplete

Todos os resultados das áreas especificadas estão contidos na matriz suggestions:

{
  "suggestions": [
    {
      "placePrediction": {
        "place": "places/ChIJ5YQQf1GHhYARPKG7WLIaOko",
        "placeId": "ChIJ5YQQf1GHhYARPKG7WLIaOko",
        "text": {
          "text": "Amoeba Music, Haight Street, San Francisco, CA, USA",
          "matches": [
            {
              "endOffset": 6
            }
          ]
        },
        "structuredFormat": {
          "mainText": {
            "text": "Amoeba Music",
            "matches": [
              {
                "endOffset": 6
              }
            ]
          },
          "secondaryText": {
            "text": "Haight Street, San Francisco, CA, USA"
          }
        },
        "types": [
          "home_goods_store",
          "establishment",
          "store",
          "point_of_interest",
          "electronics_store"
        ]
      }
    }
  ]
}

Com locationBias, o local serve como um viés, o que significa que resultados próximos ao local especificado podem ser retornados, incluindo resultados fora da área especificada. No próximo exemplo, você altera a solicitação para usar locationBias:

curl -X POST -d '{
  "input": "Amoeba",
  "locationBias": {
    "circle": {
      "center": {
        "latitude": 37.7749,
        "longitude": -122.4194
      },
      "radius": 5000.0
    }
  }
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
https://places.googleapis.com/v1/places:autocomplete

Os resultados agora contêm muito mais itens, incluindo resultados fora do raio de 5.000 metros:

{
  "suggestions": [
    {
      "placePrediction": {
        "place": "places/ChIJ5YQQf1GHhYARPKG7WLIaOko",
        "placeId": "ChIJ5YQQf1GHhYARPKG7WLIaOko",
        "text": {
          "text": "Amoeba Music, Haight Street, San Francisco, CA, USA",
          "matches": [
            {
              "endOffset": 6
            }
          ]
        },
        "structuredFormat": {
          "mainText": {
            "text": "Amoeba Music",
            "matches": [
              {
                "endOffset": 6
              }
            ]
          },
          "secondaryText": {
            "text": "Haight Street, San Francisco, CA, USA"
          }
        },
        "types": [
          "electronics_store",
          "point_of_interest",
          "store",
          "establishment",
          "home_goods_store"
        ]
      }
    },
    {
      "placePrediction": {
        "place": "places/ChIJr7uwwy58hYARBY-e7-QVwqw",
        "placeId": "ChIJr7uwwy58hYARBY-e7-QVwqw",
        "text": {
          "text": "Amoeba Music, Telegraph Avenue, Berkeley, CA, USA",
          "matches": [
            {
              "endOffset": 6
            }
          ]
        },
        "structuredFormat": {
          "mainText": {
            "text": "Amoeba Music",
            "matches": [
              {
                "endOffset": 6
              }
            ]
          },
          "secondaryText": {
            "text": "Telegraph Avenue, Berkeley, CA, USA"
          }
        },
        "types": [
          "electronics_store",
          "point_of_interest",
          "establishment",
          "home_goods_store",
          "store"
        ]
      }
    },
    ...
  ]
}

Usar includePrimaryTypes

Use o parâmetro includedPrimaryTypes para restringir os resultados de uma solicitação a um determinado tipo, conforme listado na Tabela A e na Tabela B. É possível especificar uma matriz de até cinco valores. Se omitido, todos os tipos são retornados.

No exemplo a seguir, você especifica uma string input de "Futebol" e usa o parâmetro includedPrimaryTypes para restringir os resultados aos estabelecimentos do tipo "sporting_goods_store":

curl -X POST -d '{
  "input": "Soccer",
  "includedPrimaryTypes": ["sporting_goods_store"],
  "locationBias": {
    "circle": {
      "center": {
        "latitude": 37.7749,
        "longitude": -122.4194
      },
      "radius": 500.0
    }
  }
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
https://places.googleapis.com/v1/places:autocomplete

Se você omitir o parâmetro includedPrimaryTypes, os resultados poderão incluir estabelecimentos de um tipo que você não quer, como "athletic_field".

Solicitar previsões de consulta

As previsões de consulta não são retornadas por padrão. Use o parâmetro de solicitação includeQueryPredictions para adicionar previsões de consulta à resposta. Exemplo:

curl -X POST -d '{
  "input": "Amoeba",
  "includeQueryPredictions": true,
  "locationBias": {
    "circle": {
      "center": {
        "latitude": 37.7749,
        "longitude": -122.4194
      },
      "radius": 5000.0
    }
  }
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
https://places.googleapis.com/v1/places:autocomplete

A matriz suggestions agora contém previsões de lugar e de consulta, conforme mostrado acima em Sobre a resposta. Cada previsão de consulta inclui o campo text que contém uma string de pesquisa de texto recomendada. É possível fazer uma solicitação Text Search (New) para receber mais informações sobre qualquer uma das previsões de consulta retornadas.

Usar origem

Neste exemplo, inclua origin na solicitação como coordenadas de latitude e longitude. Quando você inclui origin, a API inclui o campo distanceMeters na resposta, que contém a distância em linha reta do origin até o destino. Este exemplo define a origem como o centro de São Francisco:

curl -X POST -d '{
  "input": "Amoeba",
  "origin": {
    "latitude": 37.7749,
    "longitude": -122.4194
  },
  "locationRestriction": {
    "circle": {
      "center": {
        "latitude": 37.7749,
        "longitude": -122.4194
      },
      "radius": 5000.0
    }
  }
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
https://places.googleapis.com/v1/places:autocomplete

A resposta agora inclui distanceMeters:

{
  "suggestions": [
    {
      "placePrediction": {
        "place": "places/ChIJ5YQQf1GHhYARPKG7WLIaOko",
        "placeId": "ChIJ5YQQf1GHhYARPKG7WLIaOko",
        "text": {
          "text": "Amoeba Music, Haight Street, San Francisco, CA, USA",
          "matches": [
            {
              "endOffset": 6
            }
          ]
        },
        "structuredFormat": {
          "mainText": {
            "text": "Amoeba Music",
            "matches": [
              {
                "endOffset": 6
              }
            ]
          },
          "secondaryText": {
            "text": "Haight Street, San Francisco, CA, USA"
          }
        },
        "types": [
          "home_goods_store",
          "establishment",
          "point_of_interest",
          "store",
          "electronics_store"
        ],
        "distanceMeters": 3012
      }
    }
  ]
}