O Serviço GeoNames

O Serviço GeoNames é um banco de dados público com informações geográficas sobre países, cidades e locais. Ele dispõe de uma API para acessar os diversos tipos de informações disponíveis em sua ampla base, que segue o modelo REST para publicação das informações.

A API do GeoNames é apenas para consulta (somente leitura), portanto não é possível modificar os dados dessa plataforma.

Nessa página é possível visualizar uma listagem completa das API’s oferecidas pelo GeoNames. Note que a plataforma trabalha com diversos formatos para apresentação dos dados, dentre os quais os populares JSON (JavaScript Object Notation) e XML (eXtensible Markup Language) estão disponíveis para a maioria dos serviços. Em alguns casos também é possível obter os dados no formato CSV (Comma-Separated Values, valores separados por ponto e vírgula) que podem ser úteis caso você queira integrar essas informações em algum banco de dados.

Clicando no nome de um serviço é possível visualizar sua documentação (que está centralizada nessa página). Isso é útil para obter informações gerais sobre sua utilização. O GeoNames conta com diversos serviços que podem ser muito úteis para uma ampla gama de aplicações baseadas em localização ou informações geográficas. Tome um tempo para navegar por essa página para encontrar serviços que lhe possam ser úteis.

Criando um usuário para API

Para utilizar o GeoNames é necessário a criação de um usuário, pois é dessa forma que a plataforma controla a utilização de sua API. Ela funciona com um sistema de créditos no qual cada usuário gratuito tem uma determinada quantidade de créditos diários para fazer as chamadas de serviços, que pode ser verificada nessa tabela.

Acesse a página de login da plataforma para criar seu usuário. Essa operação não tem custo e você receberá uma confirmação por e-mail.

Para poder utilizar o serviço é necessário realizar mais dois passos:

  1. Confirmar seu endereço de email: ao criar seu usuário o GeoNames encaminha um email com um link de confirmação, usado para saber se o seu endereço de email é valido. Verifique sua caixa de emails e clique no link de confirmação.
    1. Ativar o uso da API: após a confirmação do email é necessário entrar na tela de gerenciamento de conta nesse endereço. Lá há uma seção chamada Free Web Service, onde logo abaixo você deve encontrar a frase: the account is not yet enabled to use the free web services. Click here to enable.. Clique no link Click here to enable para habilitar seu usuário a utilizar os serviços web do GeoNames., conforme ilustrado abaixo:

Guarde o nome de usuário escolhido, ele será necessário para fazer as chamadas de API.

Testando o GeoNames

Para nosso exercício vamos utilizar o serviço countryInfo, que nos traz uma série de informações de todos os países cadastrados no banco de dados da plataforma, tais como:

  • Capital
  • Código ISO
  • Área do país em quilômetros quadrados
  • População

Para realizar os testes vamos usar a ferramenta curl, um utilitário de linha de comando presente nos sistemas baseados em UNIX e Linux que nos permite compor chamadas HTTP rapidamente.

O curl também esta disponível para Windows e pode ser baixado através desse link.

No macOS abra o aplicativo Terminal e digite o seguinte comando no Bash:

curl "http://api.geonames.org/countryInfo?username=[SeuUsername]&country=BR,US"

Algumas coisas importantes a notar no comando:

  • Substitua o parâmetro username ([SeuUsername]) com o nome de usuário criado no passo anterior. Remova as chaves ([]), deve ser passado apenas o nome do usuário;
  • O parâmetro country é uma lista de códigos de países separados por vírgula, sobre os quais você deseja obter as informações. Esse parâmetro pode ser omitido, o que traria a lista completa.
  • Não se esqueça de colocar as aspas duplas ” entre a URL. Isso é necessário para que o curl a interprete por completo;

O retorno deverá ser semelhante ao abaixo:

<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<geonames>
<country>
<countryCode>BR</countryCode>
<countryName>Brazil</countryName>
<isoNumeric>076</isoNumeric>
<isoAlpha3>BRA</isoAlpha3>
<fipsCode>BR</fipsCode>
<continent>SA</continent>
<continentName>South America</continentName>
<capital>Brasília</capital>
<areaInSqKm>8511965.0</areaInSqKm>
<population>201103330</population>
<currencyCode>BRL</currencyCode>
<languages>pt-BR,es,en,fr</languages>
<geonameId>3469034</geonameId>
<west>-73.985535</west>
<north>5.264877</north>
<east>-32.392998</east>
<south>-33.750706</south>
<postalCodeFormat>#####-###</postalCodeFormat>
</country>
<country>
<countryCode>US</countryCode>
<countryName>United States</countryName>
<isoNumeric>840</isoNumeric>
<isoAlpha3>USA</isoAlpha3>
<fipsCode>US</fipsCode>
<continent>NA</continent>
<continentName>North America</continentName>
<capital>Washington</capital>
<areaInSqKm>9629091.0</areaInSqKm>
<population>310232863</population>
<currencyCode>USD</currencyCode>
<languages>en-US,es-US,haw,fr</languages>
<geonameId>6252001</geonameId>
<west>-124.733253</west>
<north>49.388611</north>
<east>-66.954811</east>
<south>24.544245</south>
<postalCodeFormat>#####-####</postalCodeFormat>
</country>
</geonames>

Trata-se de um documento XML exibindo os detalhes do Brasil (código BR) e Estados Unidos (código US). Existe porém uma versão desse mesmo serviço que nos retorna os dados em JSON, que será o formato que utilizaremos ao conectar nossos Apps. Retorne ao Terminal e digite o seguinte comando:

curl "http://api.geonames.org/countryInfoJSON?username=[Seu Username]&country=BR,US"

A única modificação foi a inclusão do sufixo JSON ao final do nome do serviço countryInfo. Com isso o resultado deverá ser semelhante ao abaixo:

{
   "geonames":[
      {
         "continent":"SA",
         "capital":"Brasília",
         "languages":"pt-BR,es,en,fr",
         "geonameId":3469034,
         "south":-33.750706,
         "isoAlpha3":"BRA",
         "north":5.264877,
         "fipsCode":"BR",
         "population":"201103330",
         "east":-32.392998,
         "isoNumeric":"076",
         "areaInSqKm":"8511965.0",
         "countryCode":"BR",
         "west":-73.985535,
         "countryName":"Brazil",
         "continentName":"South America",
         "currencyCode":"BRL"
      },
      {
         "continent":"NA",
         "capital":"Washington",
         "languages":"en-US,es-US,haw,fr",
         "geonameId":6252001,
         "south":24.544245,
         "isoAlpha3":"USA",
         "north":49.388611,
         "fipsCode":"US",
         "population":"310232863",
         "east":-66.954811,
         "isoNumeric":"840",
         "areaInSqKm":"9629091.0",
         "countryCode":"US",
         "west":-124.733253,
         "countryName":"United States",
         "continentName":"North America",
         "currencyCode":"USD"
      }
   ]
}

Para facilitar a legibilidade formatamos a saída do Terminal usando o serviço JSON Formatter & Validator.

Algumas coisas curiosas e importantes sobre o JSON:

  • O documento em geral é mais legível que o XML
  • Ele é mais simples de ser criado e consumido via software
  • O volume de dados que ele trafega é significativamente menor graças a ausência das tags de fechamento e abertura típicas do XML que tornam o documento tão extenso.

E parar provar o último ponto colocado, vamos usar um outro recurso do curl. Nos exemplos anteriores ele nos retornou apenas o corpo (body) do Response, omitindo completamente os cabeçalhos. Usando o parâmetro -I o curl retorna apenas os cabeçalhos do Response, omitindo completamente o corpo.

Uma das informações que são retornadas nos cabeçalhos do Response é o tamanho do conteúdo contido no seu corpo em bytes. Esse cabeçalho é chamado de Content-Lenght (Comprimento do Conteúdo). Vamos comparar os tamanhos de corpo dos documentos XML e JSON. Retornando ao terminal digite o comando abaixo:

curl -I "http://api.geonames.org/countryInfo?username=[Seu Username]&country=BR,US"

Os cabeçalhos desse chamado serão semelhantes aos seguintes:

HTTP/1.1 200 OK
Date: Mon, 28 Nov 2016 17:36:49 GMT
Server: Apache/2.2.15 (CentOS)
Cache-Control: no-cache
Access-Control-Allow-Origin: *
Content-Length: 1256
Connection: close
Content-Type: text/xml;charset=UTF-8

O documento XML tem 1256 bytes, aproximadamente 1 KB (quilobyte). Para obtermos os mesmos cabeçalhos para o documento JSON digite o seguinte comando:

curl -I "http://api.geonames.org/countryInfoJSON?username=[Seu Username]&country=BR,US"

Resultando em:

HTTP/1.1 200 OK
Date: Mon, 28 Nov 2016 17:38:20 GMT
Server: Apache/2.2.15 (CentOS)
Cache-Control: no-cache
Access-Control-Allow-Origin: *
Content-Length: 747
Connection: close
Content-Type: application/json;charset=UTF-8

O mesmo conteúdo em formato JSON tem 747 bytes, menos de 1 KB, e aproximadamente 60% do tamanho do documento XML. É uma redução significativa considerando um documento tão pequeno como esse, imagine com uma massa de dados maior. Podemos testar isso!

Remova o parâmetro country das chamadas anteriores, o que fará com que a listagem completa de países seja retornada pelo GeoNames. Dessa vez temos números mais expressivos: 140042 bytes (~136 KB) contra 87917 (~86 KB). Mantemos uma proporção próxima de 60%, ou 40% na redução do tráfego de rede. Nossos usuários agradecem essa economia em seus planos de dados! 👏🏻

Estimo que com esse pequeno exercício eu tenha conseguido mostrar uma das razões pelas quais o JSON tem ganhado preferência dos programadores em lugar do XML.

Obtendo as bandeiras dos países

No App Countries nós incluímos a imagem com a bandeira de cada um dos países na listagem. Essa imagem também é obtida através da plataforma GeoNames. Para isso é necessário utilizar um endereço específico (http://www.geonames.org/flags/x/[codigoPais].gif), onde devemos substituir o parâmetro [codigoPais] pelo código de duas letras do país do qual desejamos obter a imagem da bandeira. O código deve ser passado em letras minúsculas, do contrário o GeoNames irá retornar um código de erro (404 Not Found). Para essa operação, também podemos usar o curl e sua capacidade de escrever o conteúdo do Response em um arquivo em disco. Voltando ao Terminal digite o comando abaixo:

curl http://www.geonames.org/flags/x/br.gif > br.gif

A saída deverá ser algo parecido com:

 % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
                                 Dload  Upload   Total   Spent    Left  Speed
100  6145  100  6145    0     0  11794      0 --:--:-- --:--:-- --:--:-- 11794

Trata-se de estatísticas de execução do Request. Verifique a pasta onde você executou o comando e você deverá encontrar agora o arquivo br.gif. Ao abri-lo você deverá visualizar a bandeira do Brasil:

Por se tratar de um Request GET para uma imagem é possível testarmos essa chamada diretamente através do browser de nossa preferência. Por exemplo, no Google Chrome, Safari ou Firefox esse endereço abrirá a imagem da bandeira dos Estados Unidos conforme ilustrado abaixo:

Em nosso App vamos obter o código do país através do campo countryCode retornado pela listagem. Esse campo vem com os códigos em letras maiúsculas, o que significa que deveremos converter para a versão em minúscula, já que o path para obter as bandeiras é Case-Sensitive.

results matching ""

    No results matching ""