Resources and Help

API documentation

Scup's API aims to extend Scup's functionalities so that external developers can share, adapt and integrate data and functionalities more freely.

Overview

API uses REST principle with JSON response format. You can also receive answers in JSONP format via "callback" name parameter. Still in BETA stage, it may undergo significant changes, so stay tuned for future updates.

Endpoint: http://api.scup.com.br/

Authentication

The authentication works from two keys, one public and one private. The public one must be sent on every API call and the private one must be used to generate a second parameter (signature), which must be sent to every call too.

Mandatory parameters (GET):

time: current Unix Time Stamp (number of seconds since 01/01/1970).
publickey: Public key. Request your keys by clicking the button at the top of the page.
signature: MD5 of the time concatenated with the private key. Request your keys by clicking the button at the top of the page.

Example:

http://api.scup.com.br/1.0/monitoramentos/?time=1308596542&publickey=VyYKI7hf&signature=1d3a0079161bb659842afab7d9c4d998

Methods

1) List of Monitorings

URL:

http://api.scup.com.br/1.0/monitoramentos

Authentication:

Example of Response:

{
   "data":
      [
         {       
            "id": "4682",
            "nome":"Monitoramento Teste",
            "descricao":"",
            "numitensmes":"955",
            "numbuscas":"11" 
         },
         {
            "id":"4685",
            "nome":"Concorrentes",
            "descricao":"Monitoramento dos concorrentes",
            "numitensmes":"1054",
            "numbuscas":"4"
         }
      ],
   "total":2
}

2) Search Listing

URL:

http://api.scup.com.br/1.0/buscas/<monitoramento-id>/

Authentication:

Example of Response:

{
   "data":
      [
         {
            "id":"16972",
            "campo1":"teclado",
            "campo2":"pt",
            "campo3":"",
            "periodoexecucao":"9",
            "ultimachecagem":"2011-06-15 17:56:54",
            "pausado":"0",
            "servico":"Twitter",
            "tipo":"twittersearch"
         }
      ],
   "total":1
}

3) List of Items

URL:

http://api.scup.com.br/1.0/itens/<monitoramento-id>/

Authentication:

Parameters (GET):

data (optional)
Items' publication data range. Format: "<data-inicial>|<data-final>", in which date's format is "dd-mm-yyyy".
Example: http://api.scup.com.br/1.0/itens/35/?data=23-04-2010|26-07-2010
tag (optional)
Filter by specific tags. Format: "<tag1>|<tag2>|<tag3>|...|<tagn>".
Example: http://api.scup.com.br/1.0/itens/35/?tag=reclamacoes|criticas
classificacao (optional)
Filter by rating. Possible values: "positive", "negative", "neutral".
Example: http://api.scup.com.br/1.0/itens/35/?classificacao=positivo
fonte (optional)
Filter by specific searches. Format: "<id1>|<id2>|<id3>".
Example: http://api.scup.com.br/1.0/itens/35/?fonte=23|45
ipp (items per page) (optional)
Number of items to be returned on the page. Limited to 100.
Example: http://api.scup.com.br/1.0/itens/35/?ipp=80
page (optional)
Page to be listed.
Example: http://api.scup.com.br/1.0/itens/35/?page=2

Example of Response:

[
   {
      "Item":
         {
            "id":"11313",
            "titulo":"Facebook Search",
            "corpo": 
               {
                  "corpo_titulo":"",
                  "corpo_descricao":"Up Ess\u00eancia Manaus - Fantasy by Britney Spears",
                  "permalink":"http:\/\/www.facebook.com\/profile.php?id=1517303830&v=wall&story_fbid=117192518367853",
                  "foto":"http:\/\/graph.facebook.com\/1517303830\/picture\/"
               },
            "adicional":"",
            "publicado":"2011-06-15 17:56:17",
            "classificacao":"negativo",
            "numrespostas":"0",
            "monitoramento_id":"4682",
            "impactotwitter":"0",
            "impactoblogs":"0",
            "impactoyoutube":"0",
            "original_id":"0",
            "num_replicas":"0",
            "coletado":"2011-06-15 17:57:40",
            "usuario_id":"10394",
            "busca_id":"16965"
         },
      "Tipo":
         {
            "nome":"facebooksearch",
            "site":"Facebook",
            "servico":"Facebook",
            "acao":"Busca"
         },
      "Tags":
         [
            {
               "id":"5613",
               "nome":"1"
            },
            {
               "id":"5614",
               "nome":"2"
            }
         ],
      "Busca":
         {
            "destaque":"0",
            "campo1":"hoje",
            "campo2":"all"
         },
      "Usuario":
         {
            "idempresa":"",
            "id":"10394",
            "total":"1",
            "blog_count":"0",
            "youtube_count":"0",
            "location":"",
            "description":"",
            "name_twitter":"",
            "name_facebook":"Andrea Brandizzi"
         }
   }
]

4) List of Users

URL:

http://api.scup.com.br/1.0/relacionamentos/<monitoramento-id>/

Authentication:

Parameters (GET):

servico (optional)
Social media. Possible values: "twitter", "blog", "flickr", "youtube", "yahooanswers", "facebook", "slideshare", "vimeo".
Example: http://api.scup.com.br/1.0/relacionamentos/35/?servico=twitter
ipp (items per page) (optional)
Number of users to be returned on the page. Limited to 100.
Example: http://api.scup.com.br/1.0/relacionamentos/35/?ipp=80
page (optional)
Page to be listed.
Example: http://api.scup.com.br/1.0/relacionamentos/35/?page=2

Example of Response:

[
   {
      "data":
         [
            {
               "id":"4411",
               "total":"45",
               "idempresa":"",
               "idtwitter":"",
               "idyoutube":"",
               "idblog":"",
               "idflickr":"",
               "idyahooanswers":"",
               "idfacebook":"193824160646270",
               "idvimeo":"",
               "idslideshare":"",
               "anotacoes":"",
               "foto":"http:\/\/graph.facebook.com\/193824160646270\/picture",
               "followers_count":"0",
               "blog_count":"0",
               "youtube_count":"0",
               "location":"",
               "description":"",
               "name_twitter":"",
               "name_facebook":"Vivo",
            }
         ],
      "total":1
   }
]

5) List of User Items

URL:

http://api.scup.com.br/1.0/historicos/<monitoramento-id>/

Authentication:

Parameters (GET):

id (required, if the parameter user is not specified)
User internal ID (on Scup)
Example: http://api.scup.com.br/1.0/historicos/35/?id=5183
servico (required when the parameter usuario) is specified)
Social media. Possible values: "twitter", "blog", "flickr", "youtube", "yahooanswers", "facebook", "slideshare", "vimeo".
Example: http://api.scup.com.br/1.0/historicos/35/?servico=twitter&usuario=tgthies
usuario (required, if the parameter id is not specified)
User ID (on the service):
Example: http://api.scup.com.br/1.0/historicos/35/?servico=twitter&usuario=tgthies
ipp (items per page) (optional)
Number of users to be returned on the page. Limited to 100.
Example: http://api.scup.com.br/1.0/historicos/35/?ipp=80
page
Page to be listed. (optional)
Example: http://api.scup.com.br/1.0/historicos/35/?page=2

Example of Response:

[
   {
      "Item":
         {
            "id":"8858",
            "titulo":"Facebook Wall",
            "corpo":
               {
                  "corpo_titulo":"",
                  "corpo_descricao": "PICTURE: http:\/\/profile.ak.fbcdn.net\/hprofile-ak-snc4\/211084.jpg",
                  "permalink":"http:\/\/www.facebook.com\/profile.php?id=193824160646270",
                  "foto":"http:\/\/graph.facebook.com\/193824160646270\/picture\/"
               },
            "adicional":"",
            "publicado":"2011-06-15 15:52:57",
            "classificacao":"0",
            "numrespostas":"0",
            "monitoramento_id":"4682",
            "impactotwitter":"0",
            "impactoblogs":"0",
            "impactoyoutube":"0",
            "impactofacebooklikes":"0",
            "impactofacebookcomments":"0",
            "original_id":"0",
            "num_replicas":"0",
            "coletado":"2011-06-15 17:45:05",
            "usuario_id":"4411",
            "busca_id":"16972"
         },
      "Tipo":
         {
            "nome":"facebookwall",
            "site":"Facebook",
            "servico":"Facebook",
            "acao":"Mural"
         },
      "Tags":
         [
         ],
      "Busca":
         {
            "destaque":"0",
            "campo1":"vivo",
            "campo2":""
         },
      "Usuario":
         {
            "idempresa":"",
            "id":"4411",
            "total":"45",
            "blog_count":"0",
            "youtube_count":"0",
            "location":"",
            "description":"",
            "name_twitter":"",
            "name_facebook":"Vivo"
         }
   }
]

6) Tagging

URL:

http://api.scup.com.br/1.0/tagueia/<monitoramento-id>/

Authentication:

Parameters (POST):

itens
Id of the items that will be tagged (comma separated). Limited to 1000 items.
tags_incluir
Name of the tags that will be applied to the item, separated by commas. If the tag does not exist, it will be created.
tags_retirar
Name of the tags that will be removed from the item, separated by commas.
Example: http://api.scup.com.br/1.0/tagueia/4689
itens=17438,17439&tags_incluir=urgente,atendimento&tags_retirar=classificar,responder

Example of Response:

{
 "status":"ok",
 "data":
  {
     "17438":
      {
          "incluir":
             [
                 "urgente",
                 "atendimento"   
             ],
          "excluir":
             [
                 "classificar",
                 "responder"
             ]
      },
     "17439":
      {
         "incluir":
           [
                 "urgente",
                 "atendimento"
           ],
         "excluir":
           [
                 "classificar",
                 "responder"
           ]
      }
  }
}

7) Classification

URL:

http://api.scup.com.br/1.0/classifica/<monitoramento-id>/

Authentication:

Parameters (POST):

itens
Id of the items that will be classified (comma separated). Limited to 1000 items.
classificacao
Classification to be applied to the items. Possible values: "positive", "negative", "neutral" or "remove" to remove the classification
Example: http://api.scup.com.br/1.0/classifica/4689
itens=17955,17956&classificacao=positivo

Example of Response:

 {
 "status":"ok",
 "data":
   [
      "17955",
      "17956"
   ]
 }

8) Reply an item

URL:

http://api.scup.com.br/1.0/respondeItem/<monitoramento-id>/

Authentication:

Parameters (POST):

item
Id of the item that will be replied.
conta
Account that will be used to post messages on the social media (the account must be registered in Scup).
mensagem
The message that will be posted.
Example: http://api.scup.com.br/1.0/respondeItem/4689
item=17439&conta=scup_&mensagem=Nossos tutoriais estão em http://on.fb.me/nrSFI5 conheça!!!

Example of Response:

```
 [
 "Mensagem agendada com sucesso"
 ]
```

9) Remove items

URL:

http://api.scup.com.br/1.0/removeItens/<monitoramento-id>/

Authentication:

Parameters (POST):

itens
Id of the items that will be removed (comma separated), limited to 1100.
Example: http://api.scup.com.br/1.0/removeItens/4689
itens=17439,17440,17441

Example of Response:

```
 [
 "Itens removidos com sucesso"
 ]
```

Error Messages

Rate limit

API has calls limit per hour; if this limit is reached, the following message will be returned:

{
   "erro":"Atingido limite de chamadas",
   "tempo":2154
}

The time is the number of seconds required for the next call.

Invalid monitoring

When the informed monitoring ID does not exist or you do not have the permission to access monitoring data, the following message will be returned:

{
   "erro":"Monitoramento não encontrado"
}

Resources and Help

API documentation

Scup's API aims to extend Scup's functionalities so that external developers can share, adapt and integrate data and functionalities more freely.

Overview

Authentication

Methods

1) List of Monitorings

2) Search Listing

3) List of Items

4) List of Users

5) List of User Items

6) Tagging

7) Classification

8) Reply an item

9) Remove items

Error Messages

Rate limit

Invalid monitoring

From our Blog

What a monitoring of the 2012 Oscars can teach you on social media operation

Check out the importance of Scup Social in the operation of social networks of the second largest private bank in Brazil

Grammy 2012: how to monitor a big event through social media

Contact Us

Info

Support

Comercial

Address

Channels

API

Feedback