Entrar

Documentação da API

Para se cadastrar na API, clique aqui.

1. Sobre a documentação

Seja bem vindo à documentação da API do Atlas da Notícia.

O Atlas da Notícia é uma iniciativa para mapear veículos produtores de notícias – especialmente de jornalismo local – no território brasileiro.

Esta é uma API que implementa o protocolo REST para a comunicação com os sistemas com uma autenticação do tipo JWT para a segurança das aplicações.

Esta página contém aspectos mais técnicos sobre a API e seu uso. Caso ainda esteja no começo da sua experiência com a APIs e de compreensão de endpoints, por favor recorra primeiro a este documento, que detalha o passo a passo inicial para usar esse recurso.

2. Autenticação

A API conta com o padrão JWT para autenticar seus usuários.

Para que você possa autenticar, é necessário ter um usuário cadastrado no nosso sistema. Caso ainda não tenha, faça cadastro aqui.

Para acessar os endpoints da API você deve usar o token como Bearer, incluindo-o no Header de sua requisição.

Com o usuário cadastrado, você pode realizar uma solicitação POST na nossa API com as seguintes informações:

2.1 ENDPOINT

https://api.atlas.jor.br/api/v1/auth/login

2.2.1 JSON Request

{
"email": "seu@email",
"password": "sua senha"
}

2.2.2 Resposta com o token será enviada para você

        {
            "access_token": "seu_token",
            "token_type": "bearer",
            "expires_in": 3600
        }

2.3 RENOVANDO O TOKEN

Para renovar o token da sua aplicação, basta realizar o refresh do mesmo pela API. Neste Endpoint, você vai realizar um POST passando o token como Bearer token no Header da Requisição de acordo com o exemplo abaixo:

2.3.1 Endpoint

https://api.atlas.jor.br/api/v1/auth/refresh

Resposta com o novo token será enviada para você, no mesmo formanto do primeiro token.

2.4 COLUNAS DO JSON DO TOKEN

COLUNAVALOR
access_tokenToken de acesso para a API
token_typeTipo de token
expires_inTempo em segundos de validade do token

3. Endpoints de dados

Endpoints são as URL’s que a API provê para o retorno dos dados. A API do Atlas da Notícia possui diversos endpoints, cada um retornando um conjunto diferente de informações.

A URL base da aplicação é: https://api.atlas.jor.br/

A aplicação tem um controle de versão, caso a API seja atualizada de maneira a impactar nas aplicações-clientes. A versão é sempre colocada após a URL base: https://api.atlas.jor.br/api/versão

A url então deve ficar no seguinte formato: https://api.atlas.jor.br/api/v1

Após a versão, é necessário incluir o endpoint desejado para realizar a busca.

3.1 FILTROS

A API é preparada para receber filtros de acordo com os campos desejados na consulta. Para facilitar a descoberta dos campos, a aplicação dispõe para cada endpoint, um método que retorna os campos disponíveis.

Os tipos de filtros disponíveis são:

TIPOREPRESENTAÇÃODESCRIÇÃO
EqualidadeParâmetro padrão na URLÉ um parâmetro comum na URL, baseado nos campos disnívies no endpoint
ParcialidadelkÉ o LIKE do SQL, onde temos uma busca parcial de um conteúdo do tipo String
AgrupamentoParâmetro do tipo array na URLÉ o IN do SQL. Para que o sistema filtre nesse formato, é necessário enviar como array.
Maior IgualgtDefine o início de um range de dados.
Menor IgualltDefine o fim de um range de dados.

3.1.2 Exemplos de filtros

  • Equalidade: https://api.atlas.jor.br/api/v1/endpoint?parametro=valor
  • Parcialiade: https://api.atlas.jor.br/api/v1/endpoint?parametro[lk]=valor
  • Agrupamento: https://api.atlas.jor.br/api/v1/endpoint?parametro[]=valor1¶metro[]=valor2...
  • Maior Igual: https://api.atlas.jor.br/api/v1/endpoint?parametro[gt]=valor
  • Menor Igual: https://api.atlas.jor.br/api/v1/endpoint?parametro[lt]=valor
  • Between: https://api.atlas.jor.br/api/v1/endpoint?parametro[gt]=valor¶metro[lt]=valor

3.1.3 Campos

A API conta com a possibilidade de filtrar quais campos serão retornados. Para isso, é necessário enviar um parâmetro na url chamado field.

Exemplo: https://api.atlas.jor.br/api/v1/endpoint?field[]=campo_1&field[]=campo_2&...

4. Retorno de dados por endpoints

4.1 ATLAS ANALYTIC

Endpoint que retorna uma lista de veículos de acordo com os filtros.

4.1.2 Retorna os dados

GET: /data/analytic

4.1.3 Retorna as definições

GET: /data/analytic/definitions

Retorno (Definições):

    [
      "id",
      "nome_veiculo",
      "fonte",
      "segmento",
      "cidade",
      "cod_mun_ibge",
      "estado",
      "regiao",
      "address",
      "annotations",
      "email",
      "num_funcionarios",
      "periodicity",
      "another_periodicity",
      "eh_jornal",
      "eh_site_pago",
      "data_fechamento"
    ]

4.1.4 Retorno do endpoint (amostra)

    [
      {
        "id": 5114,
        "nome_veiculo": "A GAZETA DO ACRE",
        "fonte": "Atlas da Notícia",
        "segmento": "Impresso",
        "cidade": "Rio Branco",
        "cod_mun_ibge": "1200401",
        "estado": "AC",
        "regiao": "Norte",
        "address": "Av Antonio da Rocha Viana, 1503. Vila Ivonte",
        "annotations": null,
        "email": "agazeta.jornal@gmail.com",
        "num_funcionarios": "6 a 9 colaboradores",
        "periodicity": "daily",
        "another_periodicity": null,
        "eh_jornal": 1,
        "eh_site_pago": 0,
        "data_fechamento": null,
        "business_models": [
          {
            "id": 1,
            "name": "Assinatura\/paywall",
            "created_at": "2019-10-29 00:21:45",
            "updated_at": "2019-10-29 00:21:45",
            "deleted_at": null,
            "pivot": {
              "media_id": 5114,
              "business_model_id": 1
            }
          }
        ],
        "features": [
          {
            "id": 4,
            "name": "Noticiário em tempo real",
            "created_at": "2019-10-29 00:21:45",
            "updated_at": "2019-10-29 00:21:45",
            "deleted_at": null,
            "pivot": {
              "media_id": 5114,
              "feature_id": 4
            }
          },
          {
            "id": 5,
            "name": "Opinião\/colunistas",
            "created_at": "2019-10-29 00:21:45",
            "updated_at": "2019-10-29 00:21:45",
            "deleted_at": null,
            "pivot": {
              "media_id": 5114,
              "feature_id": 5
            }
          },
          {
            "id": 7,
            "name": "Possui alguma edição impressa",
            "created_at": "2019-10-29 00:21:45",
            "updated_at": "2019-10-29 00:21:45",
            "deleted_at": null,
            "pivot": {
              "media_id": 5114,
              "feature_id": 7
            }
          },
          {
            "id": 8,
            "name": "Redes sociais",
            "created_at": "2019-10-29 00:21:45",
            "updated_at": "2019-10-29 00:21:45",
            "deleted_at": null,
            "pivot": {
              "media_id": 5114,
              "feature_id": 8
            }
          }
        ],
        "collaborators": [
          {
            "id": 3,
            "name": "Estudante",
            "created_at": "2019-10-29 00:21:45",
            "updated_at": "2019-10-29 00:21:45",
            "deleted_at": null,
            "pivot": {
              "media_id": 5114,
              "collaborator_id": 3
            }
          }
        ],
        "media_channels": [
          {
            "id": 249,
            "channel_id": 1,
            "link": "https:\/\/agazetadoacre.com\/",
            "media_id": 5114,
            "created_at": "2019-10-29 00:24:32",
            "updated_at": "2019-10-29 00:24:32",
            "deleted_at": null,
            "channel": {
              "id": 1,
              "name": "Site",
              "text_hint": "Cole aqui a URL do veículo, se houver. É um item importante para nós, e nos ajudará na validação de sua sugestão - mas entendemos que alguns veículos nem site têm, por isso não é obrigatório. Agradecemos o esforço!",
              "created_at": "2019-10-29 00:21:45",
              "updated_at": "2019-10-29 00:21:45",
              "deleted_at": null
            }
          },
          {
            "id": 1100,
            "channel_id": 2,
            "link": "https:\/\/twitter.com\/agazetadoacre",
            "media_id": 5114,
            "created_at": "2019-10-29 00:24:32",
            "updated_at": "2019-10-29 00:24:32",
            "deleted_at": null,
            "channel": {
              "id": 2,
              "name": "Twitter",
              "text_hint": "Se houver, favor colocar link direto para a conta - se souber apenas o nome (ex. @observatório), acrescente antes https:\/\/twitter.com\/@nome  da pagina",
              "created_at": "2019-10-29 00:21:45",
              "updated_at": "2019-10-29 00:21:45",
              "deleted_at": null
            }
          },
          {
            "id": 1653,
            "channel_id": 3,
            "link": "https:\/\/www.facebook.com\/A-Gazeta-do-Acre-208579685881525\/",
            "media_id": 5114,
            "created_at": "2019-10-29 00:24:32",
            "updated_at": "2019-10-29 00:24:32",
            "deleted_at": null,
            "channel": {
              "id": 3,
              "name": "Facebook",
              "text_hint": "Se houver, favor colocar link direto para a conta - se souber apenas o nome (ex. @observatório), acrescente antes https:\/\/facebook.com\/@nome  da pagin",
              "created_at": "2019-10-29 00:21:45",
              "updated_at": "2019-10-29 00:21:45",
              "deleted_at": null
            }
          }
        ]
      }
    ]

4.1.5 Abaixo o que cada coluna representa

COLUNAVALOR
idIdentificação do veículo
nome_veiculoNome do veículo
fonteEm qual plataforma esses dados foram inputados
segmentoSegmento principal
cidadeCidade onde está o veículo
cod_mun_ibgeCódigo do município no IBGE
estadoEstado do veículo
regiaoRegião do veículo
addressEndereço do veículo
annotationsObservações sobre o veículo
emailEmail do veículo
num_funcionariosNúmero de funcionários do veículo
periodicityPeriodicidade do veículo
another_periodicitySe a periodicidade for diferente das disponíveis, esse campo vai conter o texto explicando.
eh_jornalDiz se o veículo é um jornal. 1 - Sim, 0 - Não
eh_site_pagoDiz se o veículo é financiado por alguém. 1 - Sim, 0 - Não
data_fechamentoSe houver data de fechamento, aqui ela estará descrita.
business_modelsModelos de negócios do veículo. Poder ter de 0 a n. (Array)
featuresCaracterísticas do veículo. Poder ter de 0 a n. (Array)
collaboratorsTipos de colaboradores que contribuíram par aos dados do veículo. Poder ter de 0 a n. (Array)
media_channelsCanais de mídia do veículo. Poder ter de 0 a n. (Array)
media_channels.n.channelDefinição do canal de mídia do veículo

4.2 CIDADES SEM VEÍCULOS (AGRUPAMENTO POR REGIÃO)

Endpoint que retorna um agregado com a quantidade de cidades sem veículos por região.

Esse é o principal endpoint, que devolve todas as colunas brutas do nosso banco de dados.

4.2.1 Retorna os dados

GET: /data/qtd-cities-without-media-region

4.2.2 Retorna as definições

GET: /data/qtd-cities-without-media-region/definitions

4.2.3 Retorno (Definições):

    [
      "regiao",
      "qtd_cidades",
      "qtd_desertos"
    ]

4.2.4 Retorno do endpoint

    [
      {
        "regiao": "Centro-Oeste",
        "qtd_cidades": 467,
        "qtd_desertos": 224
      },
      {
        "regiao": "Nordeste",
        "qtd_cidades": 1794,
        "qtd_desertos": 1146
      },
      {
        "regiao": "Norte",
        "qtd_cidades": 450,
        "qtd_desertos": 315
      },
      {
        "regiao": "Sudeste",
        "qtd_cidades": 1668,
        "qtd_desertos": 633
      },
      {
        "regiao": "Sul",
        "qtd_cidades": 1191,
        "qtd_desertos": 544
      }
    ]

4.2.5 Abaixo o que cada coluna representa

COLUNAVALOR
regiaoNome da Região.
qtd_cidadesQuantidade de cidades na região.
qtd_desertosQuantidade de cidades que não tem veículos.

4.3 CIDADES SEM VEÍCULOS POR ESTADO

Endpoint que retorna um agregado com a quantidade de cidades sem veículos por estado.

4.3.1 Retorna os dados

GET: /data/qtd-cities-without-media-state

4.3.2 Retorna as definições

GET: /data/qtd-cities-without-media-state/definitions

4.3.3 Retorno (Definições)

    [
      "estado",
      "qtd_cidades",
      "qtd_desertos"
    ]

4.3.4 Retorno do endpoint

    [
      {
        "estado": "AC",
        "qtd_cidades": 22,
        "qtd_desertos": 16
      },
      {
        "estado": "AL",
        "qtd_cidades": 102,
        "qtd_desertos": 58
      },
      {
        "estado": "AM",
        "qtd_cidades": 62,
        "qtd_desertos": 42
      }
    ]

4.3.5 Abaixo o que cada coluna representa

COLUNAVALOR
estadoNome do estado.
qtd_cidadesQuantidade de cidades no estado.
qtd_desertosQuantidade de cidades que não tem veículos.

4.4 CIDADES SEM VEÍCULOS POR ESTADO/REGIÃO

Endpoint que retorna um agregado com a quantidade de cidades sem veículos por estado e região.

4.4.1 Retorna os dados

GET: /data/qtd-cities-without-media-state-region

4.4.2 Retorna as definições

GET: /data/qtd-cities-without-media-state-region/definitions

4.4.3 Retorno (Definições)

    [
      "estado",
      "regiao",
      "qtd_desertos"
    ]

4.4.4 Retorno do endpoint

    [
      {
        "estado": "GO",
        "regiao": "Centro-Oeste",
        "qtd_desertos": 120
      },
      {
        "estado": "MS",
        "regiao": "Centro-Oeste",
        "qtd_desertos": 18
      },
      {
        "estado": "MT",
        "regiao": "Centro-Oeste",
        "qtd_desertos": 86
      },
      {
        "estado": "AL",
        "regiao": "Nordeste",
        "qtd_desertos": 58
      }
    ]

4.4.5 Abaixo o que cada coluna representa

COLUNAVALOR
estadoNome do Estado.
regiaoNome da Região.
qtd_desertosQuantidade de cidades que não tem veículos.

4.5 QUASE DESERTOS

Endpoint que retorna um agregado com os quase desertos de notícias por município.

4.5.1 Retorna os dados:

GET: /data/almost-deserts

4.5.2 Retorna as definições:

GET: /data/almost-deserts/definitions

4.5.3 Retorno (Definições):

    [
      "cidade",
      "estado",
      "regiao",
      "qtd_veiculos",
      "codmun_ibge",
      "ano",
      "populacao",
      "veiculos_por_100k_hab"
    ]

4.5.4 Retorno do endpoint

    [
      {
        "cidade": "Abadia de Goiás",
        "estado": "GO",
        "regiao": "Centro-Oeste",
        "qtd_veiculos": 2,
        "codmun_ibge": "5200050",
        "ano": 2018,
        "populacao": 8583,
        "veiculos_por_100k_hab": "23.3019"
      },
      {
        "cidade": "Abadia dos Dourados",
        "estado": "MG",
        "regiao": "Sudeste",
        "qtd_veiculos": 1,
        "codmun_ibge": "3100104",
        "ano": 2018,
        "populacao": 6972,
        "veiculos_por_100k_hab": "14.3431"
      }
    ]

4.5.5 Abaixo o que cada coluna representa

COLUNAVALOR
cidadeNome do município.
estadoNome do estado.
regiaoNome da região.
qtd_veiculosQuantidade de veículos.
codmun_ibgeCódigo do município no IBGE.
anoAno do levantamento do IBGE.
populacaoPopulação da cidade.
veiculos_por_100k_habNúmero de veículos a cada 100 mil habitantes.

4.6 VEÍCULOS POR 100 MIL HABITANTES

4.6.1 RETORNA OS DADOS

GET: /data/medias-100k-hab

4.6.2 RETORNA AS DEFINIÇÕES

GET: /data/medias-100k-hab/definitions

4.6.3 RETORNO (DEFINIÇÕES)

    [
      "cidade",
      "estado",
      "regiao",
      "qtd_veiculos",
      "codmun_ibge",
      "ano",
      "populacao",
      "veiculos_por_100k_hab"
    ]

4.6.4 Retorno do endpoint

    [
      {
        "cidade": "Abadia de Goiás",
        "estado": "GO",
        "regiao": "Centro-Oeste",
        "qtd_veiculos": 2,
        "codmun_ibge": "5200050",
        "ano": 2018,
        "populacao": 8583,
        "veiculos_por_100k_hab": "23.3019"
      },
      {
        "cidade": "Abadia dos Dourados",
        "estado": "MG",
        "regiao": "Sudeste",
        "qtd_veiculos": 1,
        "codmun_ibge": "3100104",
        "ano": 2018,
        "populacao": 6972,
        "veiculos_por_100k_hab": "14.3431"
      }
    ]

4.6.5 Abaixo o que cada coluna representa

COLUNAVALOR
cidadeNome do município.
estadoNome do estado.
regiaoNome da região.
qtd_veiculosQuantidade de veículos.
codmun_ibgeCódigo do município no IBGE.
anoAno do levantamento do IBGE.
populacaoPopulação da cidade.
veiculos_por_100k_habNúmero de veículos a cada 100 mil habitantes.

4.7 VEÍCULOS POR 100 MIL HABITANTES COM DADOS DE IDHM - POR ESTADO/REGIÃO

Endpoint que retorna um agregado com os veículos a cada 100 mil habitantes por estado e região com dados de IDHM levantados em 2010 pelo IBGE.

Nota importante: os dados populacionais foram atualizados para 2018

4.7.1 Retorna os dados

GET: /data/med-idhm-2010-state-region

4.7.2 Retorna as definições

GET: /data/med-idhm-2010-state-region/definitions

4.7.3 Retorno (Definições)

    [
      "estado",
      "regiao",
      "med_idhm",
      "med_idhm_e",
      "med_idhm_r",
      "populacao",
      "qtd_veiculos",
      "veiculos_por_100k_hab",
      "ano"
    ]

4.7.4 Retorno do endpoint

    [
      {
        "estado": "DF",
        "regiao": "Centro-Oeste",
        "med_idhm": 0.824,
        "med_idhm_e": 0.742,
        "med_idhm_r": 0.863,
        "populacao": "2974703",
        "qtd_veiculos": "259",
        "veiculos_por_100k_hab": "8.7068",
        "ano": 2018
      },
      {
        "estado": "GO",
        "regiao": "Centro-Oeste",
        "med_idhm": 0.6949837398373981,
        "med_idhm_e": 0.5960731707317073,
        "med_idhm_r": 0.6840406504065039,
        "populacao": "6921161",
        "qtd_veiculos": "470",
        "veiculos_por_100k_hab": "6.7908",
        "ano": 2018
      }
    ]

4.7.5 Abaixo o que cada coluna representa

COLUNAVALOR
estadoNome do estado.
regiaoNome da região.
med_idhmMédia do IDHM.
med_idhm_eMédia do IDHM Estado.
med_idhm_rMédia do IDHM Região.
populacaoPopulação da cidade.
qtd_veiculosQuantidade de veículos.
veiculos_por_100k_habNúmero de veículos a cada 100 mil habitantes.
anoAno do levantamento do IBGE.

4.8 MUNICÍPIOS SEM VEÍCULOS

Retorna dados sobre municípios que não possuem veículos jornalísticos, os chamados desertos de notícias.

4.8.1 Retorna os dados

GET: /data/cities-without-media

4.8.2 Retorna as definições

GET: /data/cities-without-media/definitions

4.8.3 Retorno (Definições)

    [
      "codmun",
      "municipio",
      "uf",
      "regiao",
      "populacao",
      "ano"
    ]

4.8.4 Retorno do endpoint

    [
      {
        "codmun": "5200100",
        "municipio": "Abadiânia",
        "uf": "GO",
        "regiao": "Centro-Oeste",
        "populacao": 19614,
        "ano": 2018
      },
      {
        "codmun": "5200159",
        "municipio": "Adelândia",
        "uf": "GO",
        "regiao": "Centro-Oeste",
        "populacao": 2517,
        "ano": 2018
      }
    ]

4.8.5 Abaixo o que cada coluna representa

COLUNAVALOR
codmunCódigo do município no IBGE.
municipioNome do município.
ufNome do estado.
regiaoNome da região.
populacaoPopulação da cidade.
anoAno do levantamento do IBGE.


Última atualização em