Script Python para download de dados

Para facilitar o processo de download de dados, principalmente os provenientes do projeto DETER que são frequentemente atualizados, preparamos um script em Python (testado com Python 3.5).

Trata-se de um exemplo simples, e não pode ser utilizado sem uma checagem frequente do dado que está sendo obtido, pois carece de melhorias e tratamento de possíveis exceções.

A versão apresentada está configurada para fazer o download de dados da camada pública. O suporte para autenticação dos usuários que possuem credenciais de acesso em nosso GeoServer, também está implementado, permitindo assim obter os dados mais atualizados da camada controlada. Neste modo de operação é necessário informar as credenciais, usuário e senha, além de trocar o nome da camada alvo da consulta. Ver descrição dos detalhes nos comentários do próprio script.

O script foi atualizado em 11/08/2020 e passou a suportar o download por paginação de dados respeitando o limite de nosso servidor de dados geográficos.

A forma de acesso é via padrão Web Feature Service (WFS) da Open Geospatial Consortium (OGC).

WFS GetFeature – usando paginação para baixar dados

É pré-requisito a leitura do artigo WFS GetFeature – restrição no número de registros e número total de registros de uma camada. Como descrito, uma camada pode ter muito mais dados do que é possível baixar usando apenas uma requisição.

Neste caso, é necessário realizar um procedimento de paginação que nos possibilitará obter todos os dados disponíveis na camada.

Neste exemplo, usamos o valor de 100 registros para ilustrar o processo, mas este valor pode ser ajustado até o valor máximo permitido pelo servidor, informação que também está descrita no artigo supracitado.

Os atributos de controle relevantes são:

  • count (define a quantidade de registros por página de resultado)
  • startIndex (define o número do próximo registro incluído no resultado)
  • sortBy (usado para ordenação dos dados, permitindo o funcionamento correto da paginação)

Requisição para os primeiros 100 registros, de 0 até 100.

http://terrabrasilis.dpi.inpe.br/geoserver/deter-amz/wfs?service=WFS&version=2.0.0&srsName=EPSG:4674&request=GetFeature&typeName=deter_public&CQL_FILTER=date BETWEEN '2019-01-01' AND '2019-02-01'&outputFormat=SHAPE-ZIP&count=100&sortBy=gid&startIndex=0

Requisição para os próximos 100 registros, de 101 até 200.

http://terrabrasilis.dpi.inpe.br/geoserver/deter-amz/wfs?service=WFS&version=2.0.0&srsName=EPSG:4674&request=GetFeature&typeName=deter_public&CQL_FILTER=date BETWEEN '2019-01-01' AND '2019-02-01'&outputFormat=SHAPE-ZIP&count=100&sortBy=gid&startIndex=100

Note que a ordenação é muito importante e o ideal é que seja utilizado um atributo do dado que seja único, como no exemplo, usamos o identificador gid para ordenação. Para descobrir quais atributos existem em uma camada, veja a sessão “Pesquisando os atributos de uma camada via “DescribeFeatureType” do artigo “Download de dados

WFS GetFeature – restrição no número de registros e número total de registros de uma camada

Ao publicar grandes volumes de dados via GeoServiços algumas restrições devem ser consideradas principalmente quando os recursos computacionais são escassos.

Neste sentido, existem algumas opções que nos permitem aplicar estas restrições e uma delas diz respeito ao número máximo de Features, ou de maneira mais simples, linhas na tabela entregue como resultado para cada consulta GetFeature ao serviço WFS (versão 2.0.0).

Na plataforma TerraBrasilis o número máximo de registros entregues em cada requisição está restrita a 100.000 linhas. Note que este número pode mudar e portanto você deve esperar que ele mude em algum momento no futuro. Assim sendo, a primeira dica é, consulte o valor real no documento de capacidades do serviço, fazendo a requisição GetCapabilities e procurando pelo parâmetro “CountDefault” no resultado, como se vê na figura 1.

http://terrabrasilis.dpi.inpe.br/geoserver/ows?service=wfs&version=2.0.0&request=GetCapabilities
Figura 1 – Número máximo de linhas de resultado

Outro número importante é a quantidade real de registros existentes na camada. Note que este número é diferente da restrição mencionada acima, podendo ser inferior ou superior. Em um paralelo com bancos de dados, o resultado que estamos procurando é a resposta para a seguinte query: “SELECT COUNT(*) FROM tabela”.

Para obter este valor usando uma consulta WFS, usamos o parâmetro opcional “resultType” em uma requisição GetFeature.

http://terrabrasilis.dpi.inpe.br/geoserver/wfs?SERVICE=WFS&REQUEST=GetFeature&VERSION=1.1.0&TYPENAME=prodes-cerrado:prodes_cerrado_2000_2018_uf_mun&resulttype=hits

O número esperado é entregue como valor do atributo “numberOfFeatures“, como visto na figura 2.

figura 2 – Número total de registros na camada

Download de dados

Atualmente os dados dos programas PRODES e DETER, disponíveis no portal TerraBrasilis, podem ser obtidos de duas formas:

  • Via download direto de arquivos, acessando a página de download;
  • Baixando dados via serviço WFS;

Até a presente data, 02 de maio de 2019, a ferramenta visual para download seletivo de dados usando filtros ainda não foi disponibilizada. Esta funcionalidade está em nossa lista de requisitos e será disponibilizada assim que possível.

Página de download de arquivos

A opção básica oferece arquivos por categoria de dado e bioma. São arquivos completos e compactados para quem quer todo o dado disponível.

http://terrabrasilis.dpi.inpe.br/downloads/

Baixando dados via serviço WFS

Serviços padronizados nos ajudam a flexibilizar o acesso pois permitem a utilização de ferramentas existentes no mercado que entendam estes padrões mas também permitem a construção de nossas próprias ferramentas. O serviço WFS (Web Feature Service) possui um amplo vocabulário e não pretendemos explorá-lo por completo. Iremos demonstrar apenas uma forma de obtenção de dados tomando como exemplo a camada de Alertas do projeto DETER para a Amazônia Legal.

Usando o software QGIS

Uma opção para explorar os dados usando uma interface gráfica é o software QGIS. A ferramenta padrão de adição de camada WFS permite visualizar e baixar os dados disponíveis. Os passos necessários são:

  • Inserir a URL (http://terrabrasilis.dpi.inpe.br/geoserver/ows) como fonte de dados;
  • Filtrar uma camada na lista;
  • Selecionar uma camada;
  • Criar um filtro por atributo;
  • Adicionar a camada ao mapa;
  • E por fim, salvar a camada para um arquivo.
Adição de camada WFS com filtro por atributo

Para um passo a passo, recomendo a documentação oficial do QGIS. Existe uma série de posts sobre o assunto na internet e não pretendemos escrever mais um.

Pesquisando as camadas na interface do GeoServer

O acesso à lista de camadas do GeoServer está disponível para consultas na página do TerraBrasilis. Pesquise por “Lista de todas as camadas configuradas no GeoServer“, cujo resultado irá lhe apontar para a lista conforme a seguinte figura. Os itens da lista representam as camadas e deverão apontar para seus respectivos metadados. Estando na página de metadados você pode ler as anotações sobre o dado e as formas de acesso disponibilizadas.

Pesquisando as camadas via GetCapabilities

Exemplo de solicitação dos nomes das camadas disponíveis sob o workspace deter-amz. Para esta tarefa devemos utilizar uma requisição GetCapabilities que nos retornará um XML com todas as camadas deste workspace além das demais operações que podemos aplicar ao solicitar dados via serviço.

Obter o nome da camada Alertas via serviço

Pesquisando os atributos de uma camada via DescribeFeatureType

Exemplo de solicitação dos nomes dos atributos disponíveis para a camada de dados de interesse. A operação DescribeFeatureType é usada para solicitar estas informações e o retorno pode ser visto a seguir.

Obter os nomes dos atributos da camada via serviço

Baixando os dados via GetFeature

E por fim, o exemplo de solicitação dos dados para um intervalo de tempo, usando o atributo “date”. O filtro usa CQL e é formado pelo nome do atributo de interesse e o valor ou o intervalo de valor, como neste exemplo usado para baixar os dados com data entre 01 de janeiro de 2019 a 01 de fevereiro de 2019.

CQL_FILTER=date BETWEEN ‘2019-01-01’ AND ‘2019-02-01’

http://terrabrasilis.dpi.inpe.br/geoserver/deter-amz/wfs?service=WFS&version=2.0.0&srsName=EPSG:4674&request=GetFeature&typeName=deter_public&CQL_FILTER=date BETWEEN '2019-01-01' AND '2019-02-01'&outputFormat=SHAPE-ZIP

É importante salientar que as diferenças de implementação das versões do serviço WFS 1.0.0, 1.1.0 e 2.0.0 pode causar confusão quanto à orientação dos eixos X e Y sendo necessário informar o srsName nas versões 1.1.0 e 2.0.0. veja mais detalhes na documentação do GeoServer que trata deste assunto.