Google Geocoding API: como obter a localiza��o de endere�os

Fique por dentro

Este artigo apresenta como podemos manipular geoc�digos para transform�-los em endereços. Esse tipo de procedimento � extremamente �til ao desenvolvermos aplicaç�es que façam uso de informaç�es de localizaç�o geogr�fica para fornecer algum tipo de serviço para o usu�rio. Muitas vezes, informaç�es num�ricas de latitude e longitude s�o dif�ceis de serem interpretadas, desta forma, nada melhor do que apresent�-las como endereços. Por outro lado, para armazenamento ou transfer�ncia de dados, ainda � melhor trabalhar com os dados num�ricos, uma vez que os dados textuais costumam ocupar mais espaço.

Uma t�cnica contempor�nea para o Geolocalizaç�o � a utilizaç�o do GPS (Geographic Position System). Esse recurso, largamente difundido, � encontrado em rastreadores de autom�veis, aparelhos de orientaç�o de direç�o e rotas e atualmente na maioria dos smartphones e tablets. A popularizaç�o dessa tecnologia e a possibilidade do desenvolvimento de aplicativos que utilizam o GPS do dispositivo tornou poss�vel o desenvolvimento de in�meras soluç�es em geolocalizaç�o.

Ao utilizar um GPS, as coordenadas retornadas s�o longitude, latitude e altitude. A �ltima informaç�o � retornada em metros, j� as outras s�o retornadas em graus, minutos e segundos. Nos sistemas computacionais, essas informaç�es se d�o no formato decimal, tornando-as mais f�ceis de serem tratadas, mas n�o mais f�ceis de serem interpretadas pelos usu�rios.

Ao recuperar uma determinada posiç�o, os n�meros obtidos n�o dizem muita coisa. Muitas vezes, para um geoc�digo (como s�o chamadas as coordenadas retornadas pelo GPS) ser entendido, ele precisa ser transportado para um mapa para s� ent�o o usu�rio conseguir interpret�-lo. Outra opç�o � transformar geoc�digos em notaç�es textuais, permitindo que o usu�rio, em vez de visualizar o geoc�digo, visualize o endereço formado por nome da rua, n�mero, bairro, cidade e estado.

Com o objetivo de facilitar o uso de GPS em aplicaç�es Android, este artigo apresenta a Geocoding API.

Google Geocoding API

A API Google Geocodig � uma forma de utilizar um geocodificador atrav�s de um serviço HTTP. A geocodificaç�o consiste em transformar endereços em coordenadas, como Via do Conhecimento, km1, Pato Branco, Paran� em -26.196223 e -52.689523. Tamb�m � poss�vel realizar a operaç�o inversa, transformando coordenadas em endereços.

Esse serviço � utilizado normalmente para geocodificar endereços previamente conhecidos para que torne poss�vel localiz�-los em um mapa. Essa � uma rotina custosa e demorada, por isso o ideal � que, sempre que poss�vel, o desenvolvedor persista em banco de dados ou em cache os geoc�digos de endereços est�ticos. Isso tonar� seus aplicativos mais r�pidos uma vez que melhorar� o tempo de resposta da sua aplicaç�o, pois as consultas seriam realizadas com a API apenas quando necess�rio. Esse serviço da Google est� limitado a 2.500 consultas ao dia e quem possui o pacote de serviços empresarial da Google pode realizar at� 100.000 consultas por dia.

O par�metro output deve definir o formato da resposta da solicitaç�o, sendo poss�vel informar json ou xml. A recomendaç�o da pr�pria Google � a utilizaç�o do formato JSON (notaç�o de objetos JavaScript), j� que o tamanho da sua mensagem de resposta (em bytes, por exemplo) � menor do que o tamanho da mensagem do XML.

Existe a possibilidade de utilizar o protocolo HTTP ou HTTPS. O segundo � recomendado quando os par�metros informados s�o confidenciais uma vez que o protocolo HTTPS prov� a proteç�o das informaç�es passadas por par�metro. Independente do protocolo escolhido, o formato dos par�metros de envio ou o conte�do da resposta ser� o mesmo.

Os par�metros devem seguir os padr�es de URLs, ou seja, cada par�metro deve ser separado pelo caractere �&�.

Formato JSON

O formato JSON � uma notaç�o leve de troca de dados, sendo considerada f�cil de ler e escrever. O resultado de uma requisiç�o JSON � completo. Para exemplificar, a Listagem 1 apresenta parte de uma mensagem retornada pelo Google Geocoding API. Observem que os principais dados, em especial aqueles que se referem ao endereço, se encontram no corpo da mensagem.


{
 "results" : [
 {
   "address_components" : [
   {
     "long_name" : "333-343",
     "short_name" : "333-343",
     "types" : [ "street_number" ]
   },
   {
     "long_name" : "Avenida Elisa Rosa Cola Padoan",
     "short_name" : "Av. Elisa Rosa Cola Padoan",
     "types" : [ "route" ]
   },
   {
   "long_name" : "Fraron",
   "short_name" : "Fraron",
   "types" : [ "sublocality_level_1", "sublocality", "political" ]
   },
   {
   "long_name" : "Pato Branco",
   "short_name" : "Pato Branco",
   "types" : [ "locality", "political" ]
   },
   {
   "long_name" : "Pato Branco",
   "short_name" : "Pato Branco",
   "types" : [ "administrative_area_level_2", "political" ]
   },
   {
   "long_name" : "Paran�",
   "short_name" : "PR",
   "types" : [ "administrative_area_level_1", "political" ]
   },
   {
   "long_name" : "Brasil",
   "short_name" : "BR",
   "types" : [ "country", "political" ]
   },
   {
   "long_name" : "85508",
   "short_name" : "85508",
   "types" : [ "postal_code_prefix", "postal_code" ]
   }
   ],
   "formatted_address" : "Av. Elisa Rosa Cola Padoan, 
           333-343 - Fraron, Pato Branco - PR, Brasil",
   "geometry" : {
     "bounds" : {
     "northeast" : {
       "lat" : -26.1965843,
       "lng" : -52.6890572
     },
   "southwest" : {
     "lat" : -26.1966978,
     "lng" : -52.6892667
   }
   }
      ... 
 }
],
 "status" : "OK"
}

Listagem 1. C�digo JSON em resposta a uma requisiç�o para transformar geoc�digo em endereço pela Google Geocoding API

A resposta JSON possui dois elementos b�sicos: O primeiro � o results, que cont�m uma matriz de informaç�es de endereços geocodificados e informaç�es de geometria, e o segundo � o status, que cont�m metadados sobre a solicitaç�o.

Existem outros resultados poss�veis. ZERO_RESULTS indica que nenhum resultado foi retornado e normalmente acontece porque o endereço n�o foi encontrado. Outro exemplo � o OVER_QUERY_LIMIT, que indica que a cota di�ria de consultas foi ultrapassada. Um exemplo de erro ZERO_RESULTS � apresentado na Figura 1.

Figura 1. Tela de um browser ap�s uma pesquisa sem resultado

Formato XML

O XML � uma linguagem de marcaç�o largamente utilizada nas tecnologias computacionais e na comunicaç�o com serviços web. � recomendado para documentos com dados com organizaç�es hier�rquicas, sendo um dos dois tipos de retorno poss�veis nessa API. O resultado da mesma consulta anterior feita com retorno XML � apresentado na Listagem 2.


<GeocodeResponse>
<status>OK</status>
<result>
 <type>street_address</type>
 <formatted_address>
   Av. Elisa Rosa Cola Padoan, 333-343 - Fraron, Pato Branco - PR, Brazil
 </formatted_address>
 <address_component>
   <long_name>333-343</long_name>
   <short_name>333-343</short_name>
   <type>street_number</type>
 </address_component>
 <address_component>
   <long_name>Avenida Elisa Rosa Cola Padoan</long_name>
   <short_name>Av. Elisa Rosa Cola Padoan</short_name>
   <type>route</type>
      </address_component>
      <address_component>
          <long_name>Fraron</long_name>
          <short_name>Fraron</short_name>
          <type>sublocality_level_1</type>
          <type>sublocality</type>
          <type>political</type>
      </address_component>
      <address_component>
          <long_name>Pato Branco</long_name>
          <short_name>Pato Branco</short_name>
          <type>locality</type>
          <type>political</type>
      </address_component>
      <address_component>
          <long_name>Pato Branco</long_name>
          <short_name>Pato Branco</short_name>
          <type>administrative_area_level_2</type>
          <type>political</type>
      </address_component>
      <address_component>
          <long_name>Paran�</long_name>
          <short_name>PR</short_name>
          <type>administrative_area_level_1</type>
          <type>political</type>
      </address_component>
      <address_component>
          <long_name>Brazil</long_name>
          <short_name>BR</short_name>
          <type>country</type>
          <type>political</type>
      </address_component>
      <address_component>
          <long_name>85508</long_name>
          <short_name>85508</short_name>
          <type>postal_code_prefix</type>
          <type>postal_code</type>
      </address_component>
      <geometry>
          <location>
              <lat>-26.1966585</lat>
              <lng>-52.6892299</lng>
          </location>
          <location_type>RANGE_INTERPOLATED</location_type>
          <viewport>
           <southwest>
             <lat>-26.1979900</lat>
             <lng>-52.6905109</lng>
         </southwest>
         <northeast>
           <lat>-26.1952921</lat>
           <lng>-52.6878130</lng>
             </northeast>
         </viewport>

Listagem 2. C�digo XML em resposta a uma requisiç�o para transformar geoc�digo em endereço pela Google Geocoding API

A resposta XML possui um elemento raiz chamado GeocodeResponse e, assim como o JSON, dois elementos principais de n�vel superior: status e result.

Par�metros para consulta

Para acesso ao serviço, um conjunto de par�metros deve ser informado. A partir de agora ser�o apresentados os par�metros obrigat�rios para consulta. Na sequ�ncia teremos os n�o obrigat�rios e, por fim, os par�metros usados no pacote de Serviço Empresarial.

Address, latlng e components

O par�metro address deve ser utilizado para indicar o endereço que se deseja codificar. Veja um exemplo de seu uso a seguir:

http://maps.googleapis.com/maps/api/geocode
/json?address=Via+do+conhecimento,km1,+Pato+Branco,PR

J� para pesquisas utilizando a longitude e a latitude, o par�metro latlng deve ser utilizado da seguinte forma:

http://maps.googleapis.com/maps/api/geocode
/xml?latlng=-26.196223,-52.689523

Adicionando o par�metro components � poss�vel filtrar os resultados por uma regi�o espec�fica. Como o componente � o mesmo para o mundo todo, � interessante filtrar ao menos o pa�s onde se deseja realizar a pesquisa.

Um filtro consiste em uma lista contendo componente:valor separado com uma barra vertical, o caractere |. Desta forma, apenas os valores que estiverem dentro dos filtros especificados ser�o retornados pelo WebService:

http://maps.google.com/maps/api/geocode/json?address=Via+do+conhecimento,km1,
+Pato+Branco,PR &components=country:BR

No exemplo anterior foi adicionado no par�metro o componente country, que indica a restriç�o de pa�s. Esse � o nome de um determinado pa�s ou ent�o a abreviaç�o de duas letras definida no padr�o ISO 3166-1.

Language

Determina o idioma que os resultados devem ser retornados. Caso o par�metro n�o seja informado, a API tentar� retornar o idioma nativo referente ao local do qual a solicitaç�o foi enviada.

Region

Esse par�metro fornece resultados de um dom�nio espec�fico. Por exemplo, se � realizada uma consulta utilizando o dom�nio do Brasil (region=BR), o resultado da consulta trar� um n�vel de detalhamento maior (referente ao endereço) caso seja realizada uma pesquisa com geoc�digos que se encontram dentro do territ�rio brasileiro. Entretanto, se realizada uma consulta com esse mesmo dom�nio e com um geoc�digo pertencendo � Argentina, n�o ser� recuperado um grau de detalhamento t�o grande dado que o geoc�digo n�o pertence ao dom�nio informado.

http://maps.google.com/maps/api/geocode
/json?components=administrative_area:parana|country:Brazil�ion=BR

Bounds

� poss�vel tamb�m fazer com que o serviço favoreça resultados que se encontrem em uma determinada janela de visualizaç�o. Da mesma forma que o par�metro region, o bounds apenas favorece os resultados, ele n�o impede que outros resultados relevantes sejam retornados.

Esse par�metro define coordenadas de latitude e longitude dos cantos sudoeste e nordeste da janela delimitadora, com a barra vertical | separando os valores, conforme exemplificado a seguir:

http://maps.google.com/maps/api/geocode
/json?components=administrative_area:parana|country:Brazil&
bounds=-26.7172983,-54.6192979|-22.5166644,-48.0235303

Par�metros para uso em Serviço Empresarial

Para os usu�rios que possu�rem serviço da API para empresas, devem ser inclu�dos mais dois par�metros v�lidos em sua solicitaç�o de geolocalizaç�o: client e signature. O par�metro client � o ID do cliente e o signature � uma assinatura exclusiva composta por uma chave criptogr�fica v�lida.

Estudo de caso

Utilizaremos um aplicativo que usa o GPS de um device Android para recuperar as posiç�es de latitude e longitude. Essas informaç�es ser�o apresentadas na tela do device em componentes TextView. Na tela, tamb�m haver� um bot�o que, ao ser pressionado, acessar� o serviço de Geocoding API, convertendo o geoc�digo para dado textual e apresentando-o para o usu�rio.

Vamos iniciar um novo projeto Android chamado AutoLocalizacao. Esse projeto ter� uma �nica tela, assim, teremos o arquivo activity_principal.xml e PrincipalActivity.java. O c�digo fonte referente � tela principal � apresentado na Listagem 3.


<LinearLayout xmlns:android="https://schemas.android.com/apk/res/android"
  xmlns:tools="https://schemas.android.com/tools"
  android:layout_width="match_parent"
  android:layout_height="match_parent"
  android:orientation="vertical"
  tools:context=".PrincipalActivity">

  <TextView
      android:layout_width="wrap_content"
      android:layout_height="wrap_content"
      android:text="Latitude:" />

  <TextView
      android:id="@+id/tvLatitude"
      android:layout_width="wrap_content"
      android:layout_height="wrap_content"
      android:textAppearance="?android:attr/textAppearanceLarge"
      android:text="0.0" />

  <TextView
      android:layout_width="wrap_content"
      android:layout_height="wrap_content"
      android:text="Longitude"/>


  <TextView
      android:id="@+id/tvLongitude"
      android:layout_width="wrap_content"
      android:layout_height="wrap_content"
      android:textAppearance="?android:attr/textAppearanceLarge"
      android:text="0.0" />

  <TextView
      android:layout_width="wrap_content"
      android:layout_height="wrap_content"
      android:text="Descriç�o:" />

  <TextView
      android:id="@+id/tvDescricao"
      android:layout_width="wrap_content"
      android:layout_height="wrap_content"
      android:textAppearance="?android:attr/textAppearanceLarge"
      android:text="" />

  <Button
      android:id="@+id/btBuscarDescricao"
      android:layout_width="wrap_content"
      android:layout_height="wrap_content"
      android:text="Buscar Descriç�o Local"
      android:onClick="btBuscarDescricaoOnClick" />

</LinearLayout>

Listagem 3. activity_principal.xml � Tela principal do aplicativo

Essa tela � formada por um gerenciador de layout LinearLayout (linha 01), organizado no formato vertical (linha 5). Os componentes est�o dispostos aos pares, sendo dois deles para apresentar os r�tulos (linhas 08 e 20) e dois para apresentar as informaç�es obtidas pelo GPS referentes � latitude e longitude (linhas 13 e 26). Temos tamb�m o campo descriç�o, que apresentar� os dados retornados pelo Geocoding API (linha 38) e seu r�tulo, presente na linha 33. Por fim, declaramos o bot�o que far� acesso � API da Google (linha 45).

Observem que todos os componentes visuais de entrada, processamento e sa�da de dados possuem um nome informado na tag android:id. O bot�o btBuscarDescricao possui o m�todo btBuscarDescricaoOnClick() associado ao seu evento de click, m�todo esse que deve ser codificado na classe Java. O passo seguinte � a codificaç�o dessa classe, conforme apresentado na Listagem 4.


package br.edu.utfpr.localizacao;

import android.content.Context;
import android.location.Location;
import android.location.LocationListener;
import android.location.LocationManager;
import android.os.AsyncTask;
import android.app.Activity;
import android.os.Bundle;
import android.view.View;
import android.widget.TextView;

import org.apache.http.client.HttpClient;
import org.apache.http.client.methods.HttpGet;
import org.apache.http.impl.client.DefaultHttpClient;

import java.io.BufferedReader;
import java.io.InputStream;
import java.io.InputStreamReader;
import java.net.URLEncoder;


public class PrincipalActivity extends Activity implements LocationListener {

  private TextView tvLongitude;
  private TextView tvLatitude;
  private TextView tvDescricao;

  @Override
  protected void onCreate(Bundle savedInstanceState) {
      super.onCreate(savedInstanceState);
      setContentView(R.layout.activity_principal);

      tvLongitude = (TextView) findViewById( R.id.tvLongitude );
      tvLatitude = (TextView) findViewById( R.id.tvLatitude );
      tvDescricao = (TextView) findViewById( R.id.tvDescricao );

      LocationManager lm = (LocationManager)
                  this.getSystemService( Context.LOCATION_SERVICE );

      lm.requestLocationUpdates( LocationManager.GPS_PROVIDER, 2000, 0, this );

  }

  @Override
  public void onLocationChanged(Location location) {
      double latitude = location.getLatitude();
      double longitude = location.getLongitude();

      tvLatitude.setText( String.valueOf( latitude ) );
      tvLongitude.setText( String.valueOf( longitude ) );
  }

  @Override
  public void onStatusChanged(String provider, int status, Bundle extras) {

  }

  @Override
  public void onProviderEnabled(String provider) {

  }

  @Override
  public void onProviderDisabled(String provider) {

  }

  public void btBuscarDescricaoOnClick( View v ) {
      new Conexao().execute( tvLatitude.getText().toString(),
              tvLongitude.getText().toString() );
  }

  class Conexao extends AsyncTask<String, String, String> {

   @Override
   protected String doInBackground(String... params) {
     try {
       String url = "https://maps.googleapis.com/maps/api/geocode/xml?latlng="
       + params[0] + "," + params[1];
                      
       HttpClient httpclient = new DefaultHttpClient();
       HttpGet request = new HttpGet(url);
       InputStream in = httpclient.execute(request).getEntity()
       .getContent();

       BufferedReader br = null;
       StringBuilder sb = new StringBuilder();

       br = new BufferedReader(new InputStreamReader(in));

       String line = br.readLine();

       while (line != null) {
         sb.append(line);
         line = br.readLine();

     }

     return sb.toString();

    } catch ( Exception e ) {
      return "Erro: " + e.getMessage();
    }
 }

@Override
protected void onPostExecute(String msg) {
tvDescricao.setText( msg );
}

}
}

Listagem 4. PrincipalActivity.java � Classe Java para processamento da tela principal

A classe principal utiliza as primeiras linhas para declaraç�o do pacote e importaç�o das classes utilizadas ao longo do programa (linha 01 a 20). Na linha 23 � declarada a classe principal, assim como implementada a interface LocationListener necess�ria para uso do GPS.

Da linha 25 a 27 s�o declarados os componentes visuais do aplicativo, sendo eles recuperados nas linhas 34 a 36. Na linha 38 � recuperado o serviço de GPS e, j� na linha 40, � criado um listener para rastrear mudanças de posiç�o do device Android a cada dois segundos.

O m�todo onLocationChanged(linha 45) � chamado a cada nova posiç�o do GPS, recuperando a latitude e a longitude (linhas 46 e 47) e apresentando esses dados na tela do device (linhas 49 e 50).

O m�todo btBuscarDescricaoOnClick (linha 68) trata o clique do bot�o, o qual inicia uma AsyncTask passando por par�metro os campos latitude e longitude (linha 69 e 70), recuperados a partir do GPS.

Na classe interna Conexao (linha 73), no m�todo doInBackground (linha 76), � definida uma url para utilizar a API de Geocoding. Para acesso, � utilizado um objeto HttpClient (linha 81), assim como o protocolo GET para o acesso (linha 82). Para recuperar o retorno, um objeto InputStream � instanciado (linha 83). Como o retorno � um InputStream, temos que convert�-lo para String. Para isso, � utilizado um StringBuilder (linha 87) e um BufferedReader (linha 86), o qual recebe o InputStreamReader na linha 89. Cada linha � adicionada ao objeto sb (inst�ncia do StringBuilder) a fim de criar a String completa com o resultado da chamada � Geocoding API. Ao t�rmino, essa String � retornada (linha 99).

A apresentaç�o do resultado na tela acontece no m�todo onPostExecute o qual recupera a resposta processada no m�todo doInBackground() e apresenta-a na tela (linhas 107 e 108). O resultado desse processamento � apresentado na Figura 2.

Figura 2. Resultado do aplicativo em execuç�o

Verifiquem que o resultado veio no formato XML devido ao par�metro utilizado na chamada do serviço (linha 78). Dessa forma, o resultado na �ntegra, sem formataç�o, � apresentado na tela.

Poder�amos utilizar APIs espec�ficas para a formataç�o da resposta, mas como o objetivo � simplesmente recuperar o conte�do da tag formatted_addres, utilizaremos o m�todo substring, conforme apresentado na Listagem 5.


protected String doInBackground(String... params) {
 try {
   String url = "https://maps.googleapis.com/maps/api/geocode/xml?latlng="
   + params[0] + "," + params[1]
   + "&sensor=false";
   HttpClient httpclient = new DefaultHttpClient();
   HttpGet request = new HttpGet(url);
   InputStream in = httpclient.execute(request).getEntity()
   .getContent();

   BufferedReader br = null;
   StringBuilder sb = new StringBuilder();

   br = new BufferedReader(new InputStreamReader(in));

   String line = br.readLine();

   while (line != null) {
   sb.append(line);
   line = br.readLine();

   }

   String resposta = sb.toString();

   return resposta.substring(
     resposta.indexOf( "<formatted_address>" ) + 19,
     resposta.indexOf( "</formatted_address>" )  );

   } catch ( Exception e ) {
   return "Erro: " + e.getMessage();
   }
}

Listagem 5. M�todo doInBackground() � Processamento de uma informaç�o espec�fica

Esse c�digo � modificado apenas das linhas 24 a 29, onde o resultado da consulta, um texto XML, � processado, recuperando apenas o conte�do da tag <formatted_address>, o qual possui o dado textual da posiç�o recuperada. Esse dado � apresentado na tela no componente tvDescricao. Ap�s a execuç�o, o resultado do programa � apresentado na Figura 3.

Figura 3. Resultado do aplicativo em execuç�o com a resposta formatada

Este artigo apresentou o uso do Google Geocoding API, o qual permite convers�es de geoc�digos (latitude e longitude) em endereço e vice-versa. O uso dessa API traz in�meras vantagens ao desenvolvedor, em especial para apresentaç�o de dados geogr�ficos na tela. Muitas vezes, informaç�es num�ricas de latitude e longitude n�o dizem muita coisa para o usu�rio, dessa forma, nada melhor do que apresentar uma informaç�o textual referente ao lugar.

Entretanto, para armazenamento ou transfer�ncia de dados, ainda � melhor trabalhar com os dados num�ricos referentes � longitude e latitude, uma vez que os dados textuais podem n�o ser muito precisos e costumam ocupar muito espaço se comparado aos dados num�ricos.

Como utilizar a Google Geocoding API para obter endere�os

Este artigo Google Geocoding API discute como geocódigos podem ser manipulados, transformando-os em endereços e vice-versa. Uma aplicação de exemplo será desenvolvida para aplicar os conceitos estudados.