Pronto!

Para começar a desenvolver, acesse nossa documentação do desenvolvedor.

Ativar o serviço web da API do Google Places

Para começar, orientaremos você pelo Console do Desenvolvedor do Google para realizar algumas atividades:

  1. Criar ou selecionar um projeto
  2. Ativar o serviço web da API do Google Places
  3. Criar chaves apropriadas
Continuar

Place Add

Ao adicionar um local, é possível complementar os dados no banco de dados do Google Maps com dados de seu aplicativo. Isso permite que você:

  • Atualize instantaneamente os dados no banco de dados do Google para seus usuários.
  • Envie novos locais para uma fila de moderação para adição no banco de dados de locais do Google.
  • Diferencie o seu aplicativo de outros com recursos similares.
  • Crie aplicativos direcionados a uma base de usuários ou uma localização geográfica específica.
  • Influencie os resultados de uma Places Search emitida do seu aplicativo.
  1. Visão geral
  2. Adicionar um local
  3. Excluir um local
  4. Códigos de status
  5. Mensagens de erro
  6. O parâmetro sensor

Visão geral

Quando você adiciona um local, o novo local fica disponível imediatamente em pesquisas de proximidade iniciadas pelo seu aplicativo. O novo local também entra em uma fila de moderação para ser considerado pelo Google Maps. Um local recém-adicionado não aparecerá em resultados de pesquisa de texto ou de pesquisa de radar, nem para outros aplicativos, até que tenha sido aprovado pelo processo de moderação.

Você também pode excluir locais que foram adicionados por seu aplicativo antes que sejam moderados. Depois de moderado e adicionado ao banco de dados do Google, um local não poderá mais ser excluído. Locais que não são aceitos pelo processo de moderação continuarão a ser visíveis para o aplicativo que os enviou.

Adicionar um local

Uma solicitação de adição de local é uma solicitação HTTP POST similar ao exemplo abaixo:


JSON
POST https://maps.googleapis.com/maps/api/place/add/json?key=YOUR_API_KEY HTTP/1.1
Host: maps.googleapis.com

{
  "location": {
    "lat": -33.8669710,
    "lng": 151.1958750
  },
  "accuracy": 50,
  "name": "Google Shoes!",
  "phone_number": "(02) 9374 4000",
  "address": "48 Pirrama Road, Pyrmont, NSW 2009, Australia",
  "types": ["shoe_store"],
  "website": "http://www.google.com.au/",
  "language": "en-AU"
}
      
XML
POST https://maps.googleapis.com/maps/api/place/add/xml?key=YOUR_API_KEY HTTP/1.1
Host: maps.googleapis.com

<PlaceAddRequest>
  <location>
    <lat>-33.8669710</lat>
    <lng>151.1958750</lng>
  </location>
  <accuracy>50</accuracy>
  <name>Google Shoes!</name>
  <phone_number>(02) 9374 4000</phone_number>
  <address>48 Pirrama Road, Pyrmont, NSW 2009, Australia</address>
  <type>shoe_store</type>
  <website>http://www.google.com.au/</website>
  <language>en-AU</language>
</PlaceAddRequest>
      

Observe que o caminho do URL indica o formato de entrada e de saída:

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

O URL deve conter o seguinte parâmetro:

  • key — a chave de API do aplicativo. Essa chave identifica o aplicativo para fins de gerenciamento de cotas e de forma que locais adicionados a partir dele estejam imediatamente disponíveis para seu aplicativo. Consulte Obter uma chave para saber mais.

O corpo da solicitação contém informações sobre o local. Ele deve ser estruturado de acordo com o parâmetro output especificado (JSON ou XML).

  • accuracy — a precisão do sinal de localização no qual a solicitação é baseada, expressa em metros.
  • address (recomendado para melhorar as chances de passar na moderação) — o endereço do local que você deseja adicionar. Se um local tiver um endereço formatado corretamente e legível, a chance de ele ser aprovado no processo de moderação para inclusão no banco de dados do Google Maps será maior.
  • language — o idioma em que o nome do local é exibido. Consulte a lista de idiomas permitidos e seus códigos. Observe que atualizamos com frequência os idiomas permitidos, portanto, essa lista pode não estar completa.
  • location (obrigatório) — a localização geográfica, especificada por valores de latitude e longitude, do local que você deseja adicionar.
  • name (obrigatório) — o texto com o nome completo do local. Limitado a 255 caracteres.
  • phone_number (recomendado para melhorar as chances de passar na moderação) — o número do telefone associado ao local. Se um local tiver um número de telefone formatado corretamente, a chance de ele ser aprovado no processo de moderação para inclusão no banco de dados do Google Maps será maior. Esse número deve estar em formato local ou internacional:
    • O formato local poderá diferir dependendo do país. Consulte o artigo da Wikipédia. Por exemplo, o número de telefone local do escritório da Google em Sidnei, Austrália, é (02) 9374 4000.
    • O formato internacional inclui o código do país e é prefixado por um sinal de mais (+). Por exemplo, o número de telefone internacional do escritório da Google em Sidnei, Austrália, é +61 2 9374 4000.
  • types (obrigatório) — a categoria à qual esse local pertence. Apesar de types receber uma matriz, somente um tipo pode atualmente ser especificado para um local. Solicitações XML exigem um único elemento <type>. Consulte a lista de tipos permitidos para saber mais. Se nenhum dos tipos permitidos corresponderem a esse local, pode-se especificar other.
  • website (recomendado para melhorar as chances de passar na moderação) — um URL direcionando para o site oficial desse local, como a página inicial de uma empresa. Se um local tiver um endereço de site formatado corretamente, a chance de ele ser aprovado no processo de moderação para inclusão no banco de dados do Google Maps será maior.

Respostas de Place Add

As respostas de adição de locais são retornadas no formato indicado pelo parâmetro output no caminho da solicitação de URL.

A API retorna um código de status e, se a solicitação for bem-sucedida, a resposta incluirá as seguintes propriedades para o novo local:

  • place_id: um identificador textual que identifica um local de forma exclusiva. Para recuperar informações sobre o local, passe esse identificador no campo placeId de uma solicitação Place Details. Para saber mais sobre IDs de local, consulte a visão geral de IDs de local.
  • scope: indica o escopo de place_id. Os valores possíveis para esse campo são:
    • APP: o ID de local é reconhecido apenas pelo seu aplicativo. Observação: respostas de adição de locais sempre terão um escopo de APP porque o local ainda não passou no processo de moderação.
    • GOOGLE: o ID de local está disponível para outros aplicativos e no Google Maps. Como destacado acima, respostas de adição de locais nunca terão um escopo do Google.
  • reference: um token exclusivo que pode ser usado para recuperar informações adicionais sobre esse local. Observação: o campo reference está obsoleto e foi substituído por place_id. Consulte o aviso de obsolescência nesta página.
  • id: um identificador estável exclusivo indicando esse local. Esse identificador não pode ser usado para recuperar informações sobre esse local, mas sua validade é garantida entre sessões. Ele pode ser usado para consolidar dados sobre esse local e verificar a identidade de um local entre pesquisas separadas. Observação: o id está obsoleto e foi substituído por place_id. Consulte o aviso de obsolescência nesta página.
{
  "status": "OK",
  "place_id": "CdIJN2t_tDeuEmsRUsoyG83frY4",
  "scope": "APP",
  "reference": "CiQgAAAAeTQS1RtzAyVRVjHcRiIWmWeqcAl3k7bluW7GINLDULESEHozTQhy6OHJw03ziDvY1uEaFAP_vDRhK-UbWw3Gd7Ulqm3eRjIs",
  "id": "6947fc4007436a71dbda51ef9a58627c8e8858f9"
}

Excluir um local

Um local só poderá ser excluído se:

  • For adicionado pelo aplicativo que está solicitando a exclusão.
  • A solicitação de adição não tiver sido aprovada no processo de moderação do Google Maps e, portanto, o local só for visível para o aplicativo que o adicionou.

Se você tentar excluir um local que não atenda a esses critérios, a API retornará um código de status REQUEST_DENIED.

Uma solicitação de exclusão de local é um HTTP POST com o seguinte formato:


JSON
POST https://maps.googleapis.com/maps/api/place/delete/json?key=YOUR_API_KEY HTTP/1.1
Host: maps.googleapis.com

{
  "place_id": "place ID"
}
      
XML
POST https://maps.googleapis.com/maps/api/place/delete/xml?key=YOUR_API_KEY HTTP/1.1
Host: maps.googleapis.com

<PlaceDeleteRequest>
  <place_id>place ID</place_id>
</PlaceDeleteRequest>
      

Observe que o caminho do URL indica o formato de entrada e de saída:

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

O URL deve conter o seguinte parâmetro:

  • key — a chave de API do aplicativo. Essa chave identifica o aplicativo para fins de gerenciamento de cotas e de forma que locais adicionados a partir dele estejam imediatamente disponíveis para seu aplicativo. Consulte Obter uma chave para saber mais.

O corpo da solicitação deve ser estruturado de acordo com o parâmetro output especificado (JSON ou XML). Ele deve incluir um dos dois campos seguintes:

  • place_id: uma string identificando o local que deve ser excluído retornada de uma pesquisa de local. Para saber mais sobre IDs de local, consulte a visão geral de IDs de local.
  • Como alternativa, é possível especificar reference para identificar o local. Observe que reference está obsoleto e foi substituído por place_id. Consulte o aviso de obsolescência nesta página.

Respostas de exclusão de locais

As respostas de exclusão de locais são retornadas no formato indicado pelo parâmetro output no caminho da solicitação de URL.

Uma solicitação bem-sucedida de exclusão retornará o seguinte código de status:

{
  "status": "OK"
}

Códigos de status

Códigos de status para solicitações de adição/exclusão de locais são:

  • OK indica que nenhum erro ocorreu; o local foi adicionado ou excluído com sucesso.
  • UNKNOWN_ERROR indica um erro no lado do servidor; uma nova tentativa poderá ser bem-sucedida.
  • OVER_QUERY_LIMIT indica que a cota foi ultrapassada.
  • REQUEST_DENIED indica que a solicitação foi negada. Isso pode ser causado por uma tentativa de excluir um local que foi adicionado por outro aplicativo ou que passou pelo processo de moderação do Google Maps.
  • INVALID_REQUEST geralmente indica que a solicitação tem parâmetros ausentes. Também será retornado ao tentar adicionar um local cujo name seja maior do que 255 caracteres.
  • NOT_FOUND pode ser retornado para solicitações de exclusão de locais e indica que a referência passada não pôde ser resolvida em um local.

Mensagens de erro

Quando a Google Places API Web Service retorna um código de status diferente de OK, pode haver um campo error_message adicional dentro do objeto da resposta. Esse campo contém informações mais detalhadas sobre os motivos por trás do código de status.

O parâmetro sensor

A Google Places API Web Service anteriormente exigia a inclusão do parâmetro sensor para indicar se o aplicativo usou um sensor para determinar a localização do usuário. Esse parâmetro não é mais obrigatório.

Enviar comentários sobre…

location_on
Google Places API Web Service