A plataforma do Post Denúncia usa a Google Maps Geocoding API para identificar a localização do denunciante. Quando as coordenadas (latitude e longitude) são recebidas, são submetidas à API. Ela então retorna várias informações, dentre elas o endereço, o bairro, a cidade e o estado onde o problema urbano foi reportado. Desta forma, a denúncia pode seguir para o órgão com toda a informação necessária para seu tratamento.
Para se comunicar com a API, foi desenvolvido um módulo cliente, apesar da própria equipe do Google Maps disponibilizar no GitHub uma implementação cliente em Java, aqui. Não tínhamos necessidade de algo complexo, enquanto a solução oficial contemplava não apenas a Geocoding API, mas outras APIs do Google Maps também. Construímos então uma biblioteca Java simples, que no momento deste post está na versão 1.2, e que pode ser obtida no GitHub da mesma forma, aqui.
No projeto google-geocode são duas as principais classes: GoogleGeocode e GeocodeResponse. A classe GoogleGeocode faz a comunicação com a Google Maps Geocoding API propriamente dita, passando como parâmetro as coordenadas geográficas ou um endereço específico, e convertendo a resposta em formato JSON para um objeto da classe GeocodeResponse (para realizar essa conversão, utilizamos o Jackson). Com a classe GeocodeResponse é possível conhecer o status da resposta e percorrer a lista com os resultados fornecidos pela API.
Como o Post Denúncia se restringe ao território brasileiro, as classes foram estendidas em BrazilGoogleGeocode e BrazilGeocodeResponse. Elas podem ser visualizadas aqui. Deste modo, pôde-se definir PT_br como idioma para o retorno dos resultados, e também implementar métodos específicos que retornassem adequadamente o nome do bairro e da cidade.
Tenha em mente que, ao usar o serviço de geolocalização do Google, você está criando uma dependência para sua aplicação, e precisa gerenciar isso. A Google garante disponibilidade para quem estiver em conformidade com os Termos de Serviço, que requer dentre outras coisas que sua aplicação seja pública e gratuita.
A Google define também limites de utilização. Os usuários da API padrão, não paga (nosso caso), podem fazer até 2.500 requisições por dia, e no máximo 10 solicitações por segundo. Isso é controlado através da chave da aplicação, que é passada como parâmetro na requisição. Apesar de ser uma recomendação da Google, na solução que demos não passamos a chave. O controle, nesse caso, é feito a partir do IP de onde as requisições estão sendo feitas. Se você for usar a nossa biblioteca google-geocode, tenha consciência disso. Caso queira colaborar com o projeto e implementar esta melhoria, basta fazer um pull request no repositório do Github.
Se não desejar o código do google-geocode, mas quiser usá-lo no seu projeto Maven, basta adicionar no pom.xml:
<repositories>
<repository>
<id>esign-repo</id>
<name>Esign Maven Repository</name>
<url>http://maven.esign.com.br</url>
</repository>
</repositories>
É necessário informar o repositório da Esign, para que o Maven saiba de onde baixar a dependência:
<dependencies>
<dependency>
<groupId>br.com.esign</groupId>
<artifactId>google-geocode</artifactId>
<version>1.2.0</version>
</dependency>
</dependencies>
Fique à vontade para usar! 🙂
Edição feita em 20/11/2018: Desde 11 de Junho de 2018, a Google exige que sejam usadas API keys, conforme informado oficialmente. Desta forma, a biblioteca google-geocode foi atualizada, obrigando que uma chave de API fosse passada por parâmetro. Antes de usar a biblioteca, portanto, obtenha uma API key própria.
Com a alteração, foi lançada a versão 2.0 do google-geocode. Uma boa novidade é que a nova versão está disponibilizada no repositório central do Maven, não havendo mais a necessidade de adicionar o caminho para o repositório Maven da Esign no pom.xml, como orientado no post original. Basta adicionar a dependência:
<dependencies>
<dependency>
<groupId>br.com.esign</groupId>
<artifactId>google-geocode</artifactId>
<version>2.0</version>
</dependency>
</dependencies>
Enjoy! 🙂
