Sentimonitor REST API Versão 4.0

Esta é a documentação da API do Sentimonitor Versão 4. Aqui você encontrará as instruções necessárias para consumir os dados processados pelo Sentimonitor, fazer consultas.

A API do Sentimonitor é baseada no padrão REST. Exceto onde explicitamente notado, a API é restrita ao formato JSON.

Versões da API

Atualmente, a API do Sentimonitor encontra-se na versão 5.0, e a sua documentação atualizada encontra-se aqui. Recomenda-se fortemente que se utilize a versão mais atualizada da API.

Esta página refere-se à versão 4.0 da API. Esta versão foi descontinuada, e nem todas as funcionalidades disponíveis na plataforma estão disponíveis através funcionalidades descritas abaixo. Recomenda-se a atualização para a versão 5.0 da API assim que possível.

O desenvolvmento de novas funcionalidades nas versões anteriores à versão 4.0 está descontinuado, e o seu acesso está atualmente restrito aos usuários atuais dessas APIs. Para consultar a documentação das versões anteriores, entre em contato com sup@sentimonitor.com.

Introdução

A API do Sentimonitor funciona sobre o protocolo HTTPS. A maioria das linguagens de programação populares atualmente possuem bibliotecas ou funções para utilizar este protocolo.

Convenção

Nesta documentação, todas os endpoints estão apresentados da forma

METODO /caminho/do/endpoint

O 'METODO' é o método HTTP que deve ser utilizado (em geral GET). Já o '/caminho/do/endpoint' é um caminho relativo à API, que fica em 'https://app.sentimonitor.com/api/4.0'.

Por exemplo, ao ver a seguinte declaração de endpoint

GET /indicators

deve ser feita uma requisição usando o método GET no endereço 'https://app.sentimonitor.com/api/4.0/indicators' (detalhes sobre o endpoint /indicators serão feitos abaixo).

Amigável à Navegadores

Para facilitar o aprendizado, os endpoints da API que usam o método HTTP GETpodem ser usados diretamente através do navegador de internet (como o Google Chrome ou Firefox). Basta acessar o endereço completo do endpoint, e utilizar como nome de usuário o seu endereço de nome de usuário ou email, e como senha a api_key de acesso (para detalhes, veja 'Autenticação').

Por default, as APIs retornam JSON compactado, para reduzir o tamanho total da resposta. Para ajudar na depuração, você pode adicionar o parâmetro pretty nas URLs, o que fará o output ser formatado para facilitar a leitura. Por exemplo, o endpoint /monitorings lista os seus monitoramentos. Para visualizar no navegador, você pode acessar:

https://app.sentimonitor.com/api/4.0/monitorings?pretty

HTTPS

Todas as requisições são protegidas através de HTTPS, impedindo que seus dados sejam capturados ao transitar pela internet.

Os certificados utilizados pelo Sentimonitor são assinados pelo Let’s Encrypt. Portanto, a linguagem ou biblioteca que você utilizar para conectar à API do Sentimonitor deve reconhecer tais certificados. Versões recentes dessas bibliotecas em diversas linguagens já suportam esses certificados, e nada precisa ser feito em relação a isso (consulte mais em https://letsencrypt.org/docs/certificate-compatibility/). Versões mais antigas podem precisar ser atualizadas ou de alguma configuração nesse sentido. Infelizmente, não podemos prover suporte à todas as linguagens disponíveis no mercado.

Autenticação

Todas as requisições à API devem ser autenticadas através do método Basic Access Authentication. Em resumo, você precisa adicionar um cabeçalho HTTP à requisição com as informações que descrevem a sua conta. O cabeçalho tem o seguinte formato:

Authorization: Basic {string de autenticação}

Neste cabeçalho, o 'string de autenticação' é construido da seguinte forma

string_de_autenticacao = base64( username + ":" + api_key )

O username é o nome de usuário (em geral, o email) utilizado para acessar a plataforma Sentimonitor. A api_key atualmente é fornecida individualmente para cada cliente do Sentimonitor. Por favor, entre em contato com sup@sentimonitor.com para obter a api_key de sua conta.

O username e a api_key devem ser concatenados, separados por um sinal dois-pontos (":"), e o string resultante deve ser codificado em Base64.

Exemplo

Se o seu username for someone@acme.com e sua api_key for WRawMsFO4Jqo6e72gO5YqmBvqIg=, você deve fazer o encoding base64 do string someone@acme.com:WRawMsFO4Jqo6e72gO5YqmBvqIg=, que resulta em c29tZW9uZUBhY21lLmNvbTpXUmF3TXNGTzRKcW82ZTcyZ081WXFtQnZxSWc9. Esse string resultante deve ser usado nas requisições para enviar o seguinte cabeçalho HTTP:

Authorization: Basic c29tZW9uZUBhY21lLmNvbTpXUmF3TXNGTzRKcW82ZTcyZ081WXFtQnZxSWc9

Tratamento de Erros

Se algum erro ocorrer ao processar uma chamada na API do Sentimonitor, será retornado um objeto JSON contendo uma lista de erros detectados. Utilize as mensagens para entender o que ocorreu. Por exemplo, se houver um erro ao autenticar na API, será retornado o seguinte objeto:

{
  "errors": [
    {
      "message": "Invalid authorization"
    }
  ]
}

Referência

GET /monitorings

Retorna todos os monitoramentos visiveis ao usuário. Inclui todos os monitoramentos cadastrados pelo usuário, mais os monitoramentos que o usuário possui permissão de, pelo menos, visualização.

URL do recurso: https://app.sentimonitor.com/api/4.0/monitorings

Exemplo de chamada usando cURL:

curl -H 'Authorization: Basic c29tZW9uZUBhY21lLmNvbTpXUmF3TXNGTzRKcW82ZTcyZ081WXFtQnZxSWc9' https://app.sentimonitor.com/api/4.0/monitorings

Exemplo de retorno:

{
  "monitorings": 
  [
    {
      "id": 123,
      "title": "Meu monitoramento"
    },
    {
      "id": 234,
      "title": "Monitoramento ACME"
    }
  ]
}

GET /documents

Retorna uma lista de documentos coletados pelo Sentimonitor, segundo os filtros informados.

Requer como parâmetro todos os filtros obrigatórios, e possui suporte a todos os filtros opcionais. Consulte a seção Filtragem para detalhes.

URL do recurso: https://app.sentimonitor.com/api/4.0/documents

Exemplo de chamada usando cURL para acessar os documentos do monitoramento 643 no período 01/dez/2016, 0h até 31/12/2016, 23:59:

curl -H 'Authorization: Basic c29tZW9uZUBhY21lLmNvbTpXUmF3TXNGTzRKcW82ZTcyZ081WXFtQnZxSWc9' https://app.sentimonitor.com/api/4.0/documents?start=2016-12-01+00%3A00&end=2016-12-31+23%3A59&monitorings=643

Exemplo de retorno usando cURL

{
  "data": 
  [
    {
      "id": 88651015,
      "source": "TWT",
      "sourceId": "809433297587761152",
      "parentSourceId": null,
      "title": null,
      "text": "NOVA FUNCIONALIDADE: Análise do público alvo e grupos de interesse\nhttps://t.co/tIJf7HDlIo",
      "imageUrl": null,
      "url": "http://twitter.com/129646722/status/809433297587761152",
      "language": "pt",
      "published": "2016-12-15T14:21:51Z",
      "downloaded": "2016-12-15T14:40:21Z",
      "likes": 0,
      "comments": null,
      "shares": 0,
      "author": {
        "id": 8817579,
        "source": "TWT",
        "sourceId": "129646722",
        "username": "sentimonitor",
        "name": "Sentimonitor",
        "authorUrl": "http://twitter.com/sentimonitor",
        "imageUrl": "http://pbs.twimg.com/profile_images/734722843804585984/ZAo8iABZ_normal.jpg",
        "followers": 211,
        "following": 432,
        "posts": 696
      }
    },
    {
      "id": 88011693,
      "source": "TWT",
      "sourceId": "806158595129769985",
      "parentSourceId": null,
      "title": null,
      "text": "Hoje fomos citados no @JC_RS. Você sabia que o setor de TI lidera fusões e aquisições no Brasil? https://t.co/BXCzfKOube",
      "imageUrl": null,
      "url": "http://twitter.com/129646722/status/806158595129769985",
      "language": "pt",
      "published": "2016-12-06T13:29:21Z",
      "downloaded": "2016-12-06T14:03:49Z",
      "likes": 0,
      "comments": null,
      "shares": 0,
      "author": {
        "id": 8817579,
        "source": "TWT",
        "sourceId": "129646722",
        "username": "sentimonitor",
        "name": "Sentimonitor",
        "authorUrl": "http://twitter.com/sentimonitor",
        "imageUrl": "http://pbs.twimg.com/profile_images/734722843804585984/ZAo8iABZ_normal.jpg",
        "followers": 211,
        "following": 432,
        "posts": 696
      }
    }
  ]
}

GET /authors

Retorna uma lista de autores associados aos documentos coletados pelo Sentimonitor. Os autores retornados são únicos, e são associados a todos os documentos selecionados pelos filtros informados.

Requer como parâmetro todos os filtros obrigatórios, e possui suporte a todos os filtros opcionais. Consulte a seção Filtragem para detalhes.

URL do recurso: https://app.sentimonitor.com/api/4.0/authors

Exemplo de chamada usando cURL para acessar os autores do monitoramento 643 no período 01/dez/2016, 0h até 31/12/2016, 23:59:

curl -H 'Authorization: Basic c29tZW9uZUBhY21lLmNvbTpXUmF3TXNGTzRKcW82ZTcyZ081WXFtQnZxSWc9' https://app.sentimonitor.com/api/4.0/authors?start=2016-12-01+00%3A00&end=2016-12-31+23%3A59&monitorings=643

Exemplo de retorno:

{
  "data": 
  [
    {
      "id": 8722129,
      "source": "TWT",
      "sourceId": "42502069",
      "username": "profdrpassos",
      "fullname": "Alfredo Passos",
      "authorUrl": "https://twitter.com/profdrpassos",
      "imageUrl": "http://pbs.twimg.com/profile_images/813422968919486464/vYV5cLVY_normal.jpg",
      "indicators": {
        "followers": 2446,
        "following": 982,
        "publications": 88807
      }
    },
    {
      "id": 8817579,
      "source": "TWT",
      "sourceId": "129646722",
      "username": "sentimonitor",
      "fullname": "Sentimonitor",
      "authorUrl": "http://twitter.com/sentimonitor",
      "imageUrl": "http://pbs.twimg.com/profile_images/734722843804585984/ZAo8iABZ_normal.jpg",
      "indicators": {
        "followers": 211,
        "following": 432,
        "publications": 697
      }
    }
  ],
  "total": 2,
  "offset": 0,
  "count": 2
}

GET /indicators

Retorna os indicadores calculados pelo Sentimonitor associados aos documentos filtrados.

Requer como parâmetro todos os filtros obrigatórios, e possui suporte a todos os filtros opcionais. Consulte a seção Filtragem para detalhes.

Os indicadores retornados são exatamente os mesmos exibidos na interface Web do Sentimonitor, e são controlados através do filtro viewSource. Consulte a documentação deste filtro para detalhes.

URL do recurso: https://app.sentimonitor.com/api/4.0/indicators

Exemplo de retorno:

{
  "indicators": 
  [
    {
      "name": "posts",
      "currentValue": 327,
      "previousValue": 996
    },
    {
      "name": "replication",
      "currentValue": 28,
      "previousValue": 105
    },
    {
      "name": "avgReplicationPerPost",
      "currentValue": 0.09491525423728814,
      "previousValue": 0.12946979038224415
    },
    {
      "name": "overallEngagement",
      "currentValue": 272,
      "previousValue": 2912
    },
    {
      "name": "wgtAvgEngagementPerPost",
      "currentValue": 107.25324675324676,
      "previousValue": 645.0129589632829
    },
    {
      "name": "postImpressions",
      "currentValue": 11394561,
      "previousValue": 32069387
    },
    {
      "name": "avgImpressionsPerPost",
      "currentValue": 38495.1385135135,
      "previousValue": 37508.0549707602
    }
  ]
}

Filtragem

Diversos endpoints da API do Sentimonitor requerem como parâmetros de requisição os filtros, que limitam a quais dados a requisição abrangerá. Filtros comuns incluem o período das postagens que devem ser consideradas, a rede social ou as tags aplicadas. Esses endpoints aceitam os parâmetros de filtros, descritos abaixo.

Os filtros devem ser submetidos como parâmetros das requisições. Os valores passados como filtros devem ser codificados para URLs (O chamado 'URL encoding'). Por exemplo, nos parâmetros que recebem uma lista, os valores devem ser separados por vírgula (,), que após ser codificada, é convertida em %2C

Filtros obrigatórios

Os seguintes filtros são obrigatórios, e precisam estar presentes em todas as requisições à endpoints que usem filtros:

• monitorings

Lista com os IDs dos monitoramentos que devem ser considerados, separados por vírgulas (,). Por exemplo, se o monitoramento com ID = 45 deve ser considerado, utilize

monitorings=45

Já se os monitoramentos com IDs 40, 41 e 42 devam ser considerados, utilize:

monitorings=40,41,42

Que, após o 'URL Encoding', torna-se:

monitorings=41%2C42%2C43

• start

Data e hora de inicio do período em que as postagens devem ser consideradas. Todas as postagens cuja data de publicação tenha sido igual ou posterior ao informado serão consideradas. O formato deve ser yyyy-MM-dd HH:mm. Por exemplo, para definir um período que se inicia no dia 25 de janeiro de 2016, às 10 horas e 25 minutos, utilize:

start=2016-01-25 10:25

Que, após o 'URL Encoding', torna-se:

start=2016-01-25%2010%3A25

Note que a hora deve ser informada no formato '24 horas' (por exemplo, '10' significa '10 horas da manhã', enquanto que '22' significa '10 horas da noite').

• end

Data e hora do fim do período em que as postagens devem ser consideradas. Todas as postagens cuja data de publicação tenha sido igual ou anterior ao informado serão consideradas. O formato deve ser yyyy-MM-dd HH:mm. Por exemplo, para definir um período que termina em 25 de janeiro de 2016, às 23 horas, utilize:

end=2016-01-25 23:00

Que, após o 'URL Encoding', torna-se:

end=2016-01-25%2023%3A00

Note que a hora deve ser informada no formato '24 horas'. Também observe que o horário informado no filtro 'start' deve ser anterior ao informado no filtro 'end' (caso contrário, nenhuma postagem será considerada).

Filtros Opcionais

• sources

Lista com os códigos das fontes de dados que devem ser consideradas, separadas por virgula. Apenas as postagens encontradas nas redes informadas serão consideradas. Se não for informado, todas as redes serão consideradas.

O objetivo deste filtro é permitir o agrupamento de mensagens por fonte, permitindo analizar as postagens e indicadores gerais em várias redes ao mesmo tempo. Note que este filtro não permite visualizar indicadores e nem usar os rankings específicos de uma fonte específica (para estes casos, utilize o filtro viewSource).

Note que nem todas as fontes abaixo são suportadas atualmente para monitoramento, e estão disponíveis apenas para acesso a dados históricos. Os seguintes códigos são suportados:

Código | Fonte                           | Apenas Histórico
-------|---------------------------------|-----------------
  FCG  | Facebook - Grupos               | 
  FCP  | Facebook - Páginas              | 
  GNW  | Google News                     | 
  GPL  | Google Plus                     | 
  ITG  | Instagram                       | 
  TWT  | Twitter                         | 
  YTB  | Youtube                         | 
  FCB  | Facebook - Postagens Públicas   |       Sim
  FCI  | Facebook - Perfil Individual    |       Sim
  FSQ  | FourSquare Search               |       Sim
  FSP  | FourSquare Photo Search         |       Sim
  GBL  | Google Blogs                    |       Sim
  LKD  | LinkedIn                        |       Sim
  NTC  | Notícias                        |       Sim
  OKT  | Orkut                           |       Sim
  RSS  | Feeds RSS                       |       Sim
  TMB  | Tumblr                          |       Sim
  WRP  | Wordpress                       |       Sim

Por exemplo, para considerar apenas as postagens publicadas no Facebook - Páginas ou no Twitter, inclua o parâmetro

sources=FCP,TWT

Após o 'URL Encoding', fica

sources=FCP%2CTWT

• viewSource

ID da fonte que deve ser considerada para análise. Restringe as postagens a apenas àquelas da rede informada. Ao utilizar este filtro, é possível utilizar opções específicas da rede para ranking de postagens e autores, assim como consultar os indicadores específicos da rede informada.

Observe que, diferentemente do filtro sources, este filtro é restrito a uma única fonte. Não é possível informar várias fontes separadas por vírgula neste caso.

Todas as fontes suportadas pelo filtro sources são suportadas.

Por exemplo, para se fazer análise avançada com indicadores ou ranking do Facebook - Páginas, deve se utilizar:

source=FCP

• query

Permite filtrar as postagens por aquelas que contenham as palavras ou frases informadas neste filtro. Com ele, é possível analizar um tópico específico, ignorando-se outras palavras. A query pode ser texto de acordo com o descrito em "Filtro por palavras", apresentado no Manual do Sentimonitor. Note que é necessário, assim como nos outros filtros, fazer o URL encoding do string de busca. Se este filtro não for informado, todas as postagens são consideradas.

Por exemplo, para fazer uma busca pelo texto cachorro AND quente, inclua o seguinte parâmetro:

query=cachorro AND quente

que, após o URL encoding, fica

query=cachorro%20AND%20quente

• authorName

Permite filtrar as postagens por aquelas cujo nome do autor que contenham as palavras informadas. Com ele, é possivel buscar as postagens de autores com o nome informado. Se um nome for utilizado por mais de um autor, as postagens de todos esses autores serão consideradas. Se o filtro não for informado, todos os autores são considerados.

Por exemplo, para fazer uma busca pelas postagens cujos autores conhenham a palavra sentimonitor no nome, inclua o filtro:

authorName=sentimonitor

• authorAbout

Permite filtrar as postagens por aquelas cuja descrição feita pelo autor em seu perfil contenha as palavras informadas. Por conta disso, ao ser utilizado, automaticamente restringe as postagens àquelas cujo autor tenha preenchido o campo Bio/Biografia/Sobre do seu perfil na rede social.

Por exemplo, para fazer uma buscas por autores que declararam seu interesse por futebol na descrição do perfil, inclua o filtro:

authorAbout=futebol

• sentiments

Lista com os sentimentos dos documentos que devem ser considerados. Cada postagem possui um sentimento atribuido de forma automática ou manual. Assim, esse filtro permite tratar apenas as postagens com determinados sentimentos. Se não for informado, será considerado todos os sentimentos.

Os Sentimentos disponíveis são os seguintes

Código | Sentimento
-------|--------------
   B   | Bom/Positivo
   N   | Neutro
   R   | Ruim/Negativo

Por exemplo, para considerar apenas as postagens Neutras ou positivas, inclua nos parâmetros o seguinte filtro

sentiments=B,N

Que, após o 'URL encoding', ficaria

sentiments=B%2CN

• languages

Lista de codigos de linguagem dos documentos. Permite filtrar os documentos por linguagem. Com ele, é possivel restringir os documentos a uma ou mais linguagens especificas. Se não for informado, todas as linguas são consideradas.

Os códigos suportados são os seguintes:

Código | Linguagem
-------------------
  de   | Alemão
  es   | Espanhol
  fr   | Francês
  en   | Inglês
  nl   | Holandês
  pt   | Portugues
  cs   | Tcheco

Por exemplo, para restringir as postagens àquelas em Portugues ou Inglês, adicione o seguinte filtro:

languages=pt,en

Após fazer o 'URL Encoding', fica:

languages=pt%2Cen

• tags

Lista com os IDs das tags que devem ser consideradas, separados por virgulas. Apenas os documentos com ao menos uma das tags informadas serão considerados. Por padrão, se esse filtro não for incluido, todas as tags cadastradas serão consideradas. Assim, este filtro é relevante no caso de desconsiderar postagens baseado nas tags.

Por exemplo, se desejar considerar apenas os documentos com as tags 51, 52 ou 53, inclua o parâmetro:

tags=51,52,53

Após o 'URL encoding', torna-se:

tags=51%2C52%2C53

• ignoreTags

Lista com os IDs das tags que não devem ter sido aplicadas, separados por virgulas. Apenas as postagens que não contenham nenhuma das tags informadas nesse filtros serão considerados. Por padrão, se esse filtro não for informado, nenhuma tag será considerada. Dessa forma, esse filtro é relevante para desconsiderar postagens baseados em suas tags.

Por exemplo, para desconsiderar as postagens que tenham as tags 54, 55 nem 56, adicione o parâmetro

ignoreTags=54,55,56

Após o 'URL encoding', torna-se:

ignoreTags=54%2C55%2C56

• tagExpression

Permite fazer filtragem de documentos com base em expressões com as tags. Qualquer expressão por tags suportada pelo filtro de Taga avançado (consulte o item 'Filtragem por Tags' no Manual do Sentimonitor). Se não for informado, todos as tags serão consideradas.

Este filtro possui prioridade sobre os filtros tags e ignoreTags. Portanto, se for utilizado, estes outros filtros serão ignorados.

Por exemplo, se desejar considerar todas as postagens que tenham as tags 'SAC' ou 'SPAM', inclua o seguinte parâmetro:

tagExpression='SAC' | 'SPAM'

que, após aplicar o 'URL encoding', torna-se:

tagExpression=%27SAC%27%20%7C%20%27SPAM%27

• authors

Lista com os IDs dos autores que devem ser considerados, separados por virgulas. Apenas as postagens dos autores informados nesse filtro serão considerados. Por padrão, se esse filtro não for informado, todos os autores serão considerados. Assim, esse filtro é relevante para avaliar a postagem de um grupo de autores específico.

Por exemplo, para considerar apenas as postages dos autores com ID 62 e 63, adicione o parâmetro

authors=62,63

Após o 'URL encoding', torna-se

authors=62%2C63

• authorTags

Lista com os IDs de tags aplicadas em autores que devem ser considerados. Apenas as postagens cujos autores tenham as tags informadas nesse filtro serão consideradas. Por padrão, se esse filtro não for informado, todas as tags de autores serão consideradas. Dessa forma, esse filtro é relevante para avaliar as postagens baseado nas tags aplicadas aos seus autores.

• onlyVerifiedAuthors

Booleano indicando se apenas as postagens de autores verificados ou não verificados devem ser consideradas. Se utilizado, apenas os autores com status verificado igual ao informado serão considerado. Se não for informado, todos os autores serão considerados. Suporta os valores true ou false.

Por exemplo, para considerar apenas as postagens de autores verificados, inclua o filtro

onlyVerifiedAuthors=true

• onlyWithPersonalUrl

Booleano indicando se apenas as postagens de autores com url de site pessoal devam ser consideradas ou não. Se utilizado com o valor true, apenas postagens de autores com URL pessoal serão considerados. Se for usado com o valor false, apenas autores sem URL pessoal serão considerados. Se não for informado, todos os autores são considerados.

Por exemplo, para filtrar as postagens apenas de autores com URL de perfil pessoal, inclua o parâmetro

onlyWithPersonalUrl=true

• contributors

Lista com os IDs de revisores que devem ser considerados. Apenas postagens que tenham sido revisadas pelos usuários informados serão considerados. Por padrão, todos os revisores que trabalharam em qualquer um dos monitoramentos informados (ver filtro monitorings) serão considerados. Com isso, esse filtro é relevante para as postagens em que um ou mais revisores trabalharam (por exemplo, em um processo de auditoria).

Para mais detalhes sobre o processo de revisão, veja "Revisão das Postagens e Autores" no Manual do Usuário Sentimonitor.