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 (Global Covenant of Mayors Common Reporting Framework).
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.
Instruções da API
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]§or=[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 CRF. Setores e subsetores devem ser aplicados exatamente:
| Energia estacionária | Transporte | Resíduos | |
| Edifícios residenciais | Na estrada | Descarte de resíduos sólidos | |
| Edifícios e instalações comerciais | Ferrovia | Tratamento biológico | |
| Edifícios e instalações institucionais instalações | Navegação aquática | Incineração e queima a céu aberto | |
| Edifícios industriais e instalações | Aviação | Águas residuais | |
| Agricultura | Fora de estrada | ||
| Emissões fugitivas |
| IPPU | AFOLU | Geração de energia fornecida pela rede | Emissões totais | |
| Processo industrial | Pecuária | Geração somente de eletricidade | ||
| Uso de produtos | Uso da terra | Geração CHP | ||
| Outro AFOLU | Geração de calor/frio | |||
| Geração renovável local |
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
Exemplo: Recuperar emissão direta de um subsetor específico
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.
Ferramenta de pesquisa de ID da cidade
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.