API

A API do Portal de Dados para Cidades oferece acesso gratuito e aberto aos conjuntos de dados de emissão de gases de efeito estufa da cidade para uso em sites, aplicativos e planilhas.

A API segue padrões e formatos comuns (JSON) e permite que desenvolvedores e profissionais de ação climática exportem dados do Portal de Dados para Cidades ponto a ponto ou extraindo conjuntos de dados de cidades inteiras seguindo o GCoM CRF (Pacto Global de Prefeitos pelo Clima e a Energia Marco Comum de Reporte).

A API oferece acesso a todos os pontos de dados disponíveis em todas as cidades e anos disponíveis por meio de uma sequência exclusiva no formato de um endereço de internet (URL). Ao aplicar a URL em aplicativos e documentos, os desenvolvedores e usuários podem extrair dados para uso em seu próprio contexto e certificar-se de que todos os pontos de dados sejam atualizados quando novos conjuntos de dados forem disponibilizados no Portal de Dados para Cidades ou quando os dados existentes forem atualizados.

Cada cidade no Portal de Dados tem um ID exclusivo de 7-8 dígitos. Para permitir que desenvolvedores e outros usuários extraiam dados para a cidade pretendida, a API permite procurar IDs usados no Portal de Dados para uso na construção de strings específicas.

Desenvolvedor instruções
A API do Data Portal for Cities é compatível com JSON e direta para integrar em sites, aplicativos e planilhas. Consulte a seção Instruções da API para obter detalhes. Ao implementar dados do Data Portal for Cities, IDs de cidades exclusivas são necessárias para construir sequências de URL funcionais. Para esse propósito, você pode usar a ferramenta de pesquisa de cidades ou pode solicitar uma lista de IDs para cidades em um país ou região específica. Envie solicitações para: info@dataportalforcities.org e aguarde dois dias úteis para a entrega.

 

A página da API do Data Portal for Cities permite que os usuários recuperem dados de emissão ponto a ponto ou como conjuntos de dados completos para uma determinada cidade usando uma única URL. Ao acessar URLs de API diretamente, é aconselhável usar um formatador JSON no seu navegador para obter uma saída ordenada. Há várias opções gratuitas disponíveis, por exemplo, a extensão do formatador JSON para o Chrome.

A construção da URL da API do Data Portal
Uma sequência de caracteres de URL de API válida é construída da seguinte forma:

https://dataportalforcities.org/api/emissions?city_id=[city_idvalue]&year=[year]&sector=[sector]&scope=[scope]

Base de endereço
A primeira parte (verde) da string é obrigatória e serve como o endereço URL da API.

City_id
A parte city_id (azul) da string é obrigatória e se refere ao ID da cidade em questão. Cada cidade no Data Portal for Cities recebe um ID de cidade de 6 a 8 dígitos para garantir que as cidades em o globo é identificado corretamente e cidades igualmente nomeadas não são confundidas. Para procurar uma ID de cidade específica, basta usar a Ferramenta de Pesquisa de Cidade. Para mais informações, veja a seção Instruções da Ferramenta de Pesquisa de Cidade.

Ano
O parâmetro ano (laranja) simplesmente se refere ao ano dos dados compilados. O parâmetro de dados pode ser omitido, nesse caso os dados do ano mais recente serão retornados como padrão.

Setor
Entradas de string válidas abrangem todos os setores e subsetores que fazem parte do formato de inventário Marco Comum de Reporte. Setores e subsetores devem ser aplicados exatamente:

 

 

 

 

 

 

Escopo
O escopo (vermelho) se refere a emissões diretas ou indiretas – ou ao total de ambas. Os valores válidos são simplesmente:

direto
indireto
total

Exemplos de uso
A API do Portal de Dados para Cidades abre várias maneiras de recuperar dados. Aqui estão apenas alguns exemplos:
 

Exemplo: Recuperar todos os dados de emissão de uma cidade específica

https://dataportalforcities.org/api/emissions?cityid=2618424&scope=total

 

Exemplo: Recuperar a emissão total de um setor

https://dataportalforcities.org/api/emissions?scope=total&cityid=2618424&sector=Edifícios%20residenciais

 

Exemplo: Recuperar emissão direta de um subsetor específico

https://dataportalforcities.org/api/emissions?cityid=2618424&year=2015&sector=Institutional%20buildings%20%26%20facilities&scope=direct

Códigos de erro
Todos os códigos de resposta são retornados no código de status do cabeçalho de resposta https.

200: A solicitação foi processada.

400: Solicitação incorreta. Um dos parâmetros solicitados não é válido.

404: Um dos elementos solicitados não foi encontrado.

A ferramenta de pesquisa de ID da cidade permite acesso gratuito e simples para pesquisar o ID do Data Portal for Cities de qualquer cidade representada no portal. A ferramenta pode ser facilmente implementada como um serviço distribuído e pode ser encontrada em: 

https://dataportalforcities.org/city/picker

Usando a ferramenta
A ferramenta de pesquisa de ID da cidade foi projetada para simplicidade e fácil implementação. É recomendável implementar a ferramenta usando a tag HTML <iframe>. Em sistemas de gerenciamento de conteúdo, procure por Inserir objeto externo ou similar. A ferramenta é escalável e se adapta facilmente a navegadores móveis e de grande porte.

ID da cidade para países ou regiões inteiras
Ao planejar usar dados do Portal de Dados para Cidades para um país ou região inteira, uma lista de IDs pode ser útil. Envie a solicitação para: info@dataportalforcities.org.