KPI6 API

REST API documentation

Profile

Profile | Get api keys

get
/apikeys

Header

Field Type Description
Authorization String

Users token.

HTTP/1.1 200 OK
{
  "type": "success",
  "handler": "success_get_apikeys",
  "value": {
    "apikeys": [String],
  }
}

Profile | Get consumptions

get
/consumptions

Header

Field Type Description
Authorization String

Users token.

HTTP/1.1 200 OK
{
  "type": "success",
  "handler": "success_consumptions",
  "value": {
    "plan": {
      "name": String,
      "activation": Timestamp,
      "resetInDays": Number,
    },
    "consumptions": {
      "social_name": {
        "consumptions_name": {
          "plan": Number,
          "addon": Number,
          "total": Number,
          "used": Number,
          "left": Number,
        },
        ...
      },
    },
    "insights": [String, ...]
  }
}

Profile | Get consumptions

get
/consumptions

Header

Field Type Description
Authorization String

Users token.

HTTP/1.1 200 OK
{
  "type": "success",
  "handler": "success_consumptions",
  "value": {
    "planNewLa": {
      "name": String,
      "activation": Timestamp,
      "resetInDays": Number,
    },
    "consumptions": {
        "active_audiences": {
          "plan": Number,
          "addon": Number,
          "total": Number,
          "used": Number,
          "left": Number,
        },
        ...
    },
    "insights": [String, ...]
  }
}

Profile | Get profile information

get
/profile

Header

Field Type Description
Authorization String

Users token.

HTTP/1.1 200 OK
{
  "type": "success",
  "handler": "success_get_profile",
  "value": {
    "first_name": String,
    "last_name": String,
    "email": String,
    "job_title": String,
    "business": String,
    "website": String,
    "phone": String,
    "time_zone": String,
    "planInfo": { "type": String, "activation_date": Timestamp, "plan": String },
    "verified_email": Boolean,
    "verified_phone": Boolean,
    "instagram": { "tokens": String[] },
    "twitter": { "screen_name": String, "tokens": String, "secret": String},
    "sandbox": Boolean,
    "logo": String,
    "hide_kpi6_label": Boolean,
    "anonymous_ron": Boolean,
    "chart_auto_update": String,
    "custom_settings": Object,
    "tour_mode": Boolean
  }
}

Profile | Get user quotes

get
/profile/quotes

Header

Field Type Description
Authorization String

Users token.

HTTP/1.1 200 OK
{
  "type": "success",
  "handler": "success_get_quotes",
  "value": {}
}

Profile | Get user subscriptions

get
/profile/subscriptions

Header

Field Type Description
Authorization String

Users token.

HTTP/1.1 200 OK
{
  "type": "success",
  "handler": "success_get_subscriptions"
  "value": {}
}

Profile | Get user's addons

get
/addons

Header

Field Type Description
Authorization String

Users token.

HTTP/1.1 200 OK
{
  "type": "success",
  "handler": "success_addons_get",
  "value": {
    "social_name": { 
      "addon_name": Number,
      ...
    },
    ...
  }
}

Profile | Get user's extras

get
/products

Header

Field Type Description
Authorization String

Users token.

HTTP/1.1 200 OK
{
  "type": "success",
  "handler": "success_get_extras",
  "value": [
            'share_research',
            'share_audience',
            ...
           ]
}

Profile | Get user's products

get
/products

Header

Field Type Description
Authorization String

Users token.

HTTP/1.1 200 OK
{
  "type": "success",
  "handler": "success_get_products",
  "value": [
            'marketear',
            'lookalike',
            ...
           ]
}

Profile | Update account custom settings

post
/profile/update/custom_settings
{
  "audience_segment_export": {
     "callback_url": "url"
   },
}

Header

Field Type Description
Authorization String

Users token.

Parameter

Field Type Description
audience_segment_export Object

Segment export settings.

HTTP/1.1 200 OK
{
  "type": "success",
  "handler": "success_custom_settings_update",
  "value": {...}
}

Profile | Update profile

post
/profile/update/informations
{
  "first_name": "Jack",
  "last_name": "Brown",
  "business": "KPI6",
  "job_title": "Engineer",
  "website": "https://www.kpi6.com",
  "phone": "123456789",
  "time_zone": "UTC",
  "logo": "https://www.example.com/image.png",
  "tour_mode": Boolean
}

Header

Field Type Description
Authorization String

Users token.

Parameter

Field Type Description
first_name String

First name.

last_name String

Last name.

business String

Company name.

job_title optional String

User job title.

website optional String

User website.

phone optional String

User phone number.

time_zone optional String

Timezone.

tour_mode optional String

Show tour mode.

HTTP/1.1 200 OK
{
  "type": "success",
  "handler": "success_user_update",
  "value": {...}
}

Research

Research | Clone research

post
/research/:id/clone
{
  "name": "My topic name"
}

Header

Field Type Description
Authorization String

Users token.

Parameter

Field Type Description
name String

Topic name.

description optional String

Topic description.

ai_sentimentEmotion optional Boolean

Enable or disable AI sentiment and emotion.

Default value: true

ai_sentimentEmotionComments optional Boolean

Enable or disable AI sentiment and emotion for comments.

Default value: false

ai_topics_and_entities optional Boolean

Enable or disable AI topics and entities.

Default value: false

HTTP/1.1 200 OK
{
  "type": "success",
  "handler": "success_topic_creation",
  "value": {
    "username": String,
    "id": Number,
    "topic_name": String,
    "description", String,
    "created_at": Timestamp
  }
}

Research | Add filter

post
/research/:id/filter
{
  type: "entities",
  filter: ["Donald Trump", "Vladimir Putin"]
}

Header

Field Type Description
Authorization String

Users token

Path parameters

Field Type Description
id String

Research ID

Parameter

Field Type Description
type String

Filter type

Allowed values: entities

filter Array

Filter

HTTP/1.1 200 OK
{
  "type": "success",
  "handler": "success_topic_entities_filter",
  "value": {
     "filter": {
         "entities": ["Donald Trump", "Vladimir Putin"]
      }
   }
}

Research | Count preview for posts update research

post
/research/:id/update/count

Header

Field Type Description
Authorization String

Users token.

Path parameters

Field Type Description
id String

Research ID.

Parameter

Field Type Description
update_start optional Timestamp

Topic start date in timestamp.

update_end optional Timestamp

Topic end date in timestamp.

HTTP/1.1 200 OK
{
  "type": "success",
  "handler": "success_topic_update_count",
  "value": {
     "total": Number,
     "sources": {
       "twitter": Number,
       "instagram": Number,
       "facebook": Number,
       "webdata": Number
     }
   }
}

Research | Get researches

get
/researches/:show

Header

Field Type Description
Authorization String

Users token.

Parameter

Field Type Description
show optional String

Return all or only unarchived researches

Default value: unarchived

Allowed values: unarchived, all

HTTP/1.1 200 OK
{
  "type": "success",
  "handler": "success_topic_list",
  "value": [
    {
      "ai": Object, 
      "backlog_done": Timestamp, 
      "backlog_end": Timestamp, 
      "backlog_start": Timestamp, 
      "created_at": Timestamp, 
      "description": String, 
      "id": String, 
      "keywords": Array, 
      "postsCount": Number,
      "progress": Number,
      "sandbox": Boolean, 
      "schedule": Object,
      "social": String, 
      "start_date": Timestamp, 
      "stop_date": Timestamp, 
      "threshold": Number, 
      "topic_name": String, 
      "topic_query": Array, 
      "topic_status": String, 
      "username": String
    },
    ...
  ]
}

Research | Merge research

post
/research/merge
{
  "name": "My topic name",
  "from": ["research_1", "research_2"]
}

Header

Field Type Description
Authorization String

Users token.

Parameter

Field Type Description
name String

Topic name.

from optional Array

List of Research Id to include in new research

HTTP/1.1 200 OK
{
  "type": "success",
  "handler": "success_topic_creation",
  "value": {
    "id": Number,
    "topic_name": String
  }
}

Research | New research

post
/research
{
  "name": "My topic name"
}

Header

Field Type Description
Authorization String

Users token.

Parameter

Field Type Description
name String

Topic name.

description optional String

Topic description.

ai_sentimentEmotion optional Boolean

Enable or disable AI sentiment and emotion.

Default value: true

ai_sentimentEmotionComments optional Boolean

Enable or disable AI sentiment and emotion for comments.

Default value: false

ai_topics_and_entities optional Boolean

Enable or disable AI topics and entities.

Default value: false

HTTP/1.1 200 OK
{
  "type": "success",
  "handler": "success_topic_creation",
  "value": {
    "username": String,
    "id": String,
    "topic_name": String,
    "description", String,
    "created_at": Timestamp
  }
}

Research | Share a research

post
/research/:id/share
{
  "email": "user@kpi6.com",
  "permissions": [
     "get_research",
     "update_research",
     "research_filters",
     "research_status"
   ]
}

Header

Field Type Description
Authorization String

Users token.

HTTP/1.1 200 OK
{
  "type": "success",
  "handler": "success_topic_updated"
}

Research | Start research

post
/research/:id/start

Header

Field Type Description
Authorization String

Users token.

Path parameters

Field Type Description
id String

Research ID.

Parameter

Field Type Description
backlog_start optional Timestamp

Topic start date in timestamp.

backlog_end optional Timestamp

Topic end date in timestamp.

threshold optional Number

Posts limit.

Default value: 6000000

streaming optional Boolean

Start streaming after downloading past posts.

Default value: false

confirmationTokens optional Array

Confirmation token required for full archive data.

maxComments optional Number

Max comments to download per post.

Default value: 200

HTTP/1.1 200 OK
{
  "type": "success",
  "handler": "success_topic_started",
  "value": String
}

Research | Update research posts

post
/research/:id/update

Header

Field Type Description
Authorization String

Users token.

Path parameters

Field Type Description
id String

Research ID.

Parameter

Field Type Description
update_start optional Timestamp

Topic start date in timestamp.

update_end optional Timestamp

Topic end date in timestamp.

threshold optional Number

To limit posts to update.

Default value: 0

HTTP/1.1 200 OK
{
  "type": "success",
  "handler": "success_topic_update_started",
  "value": String
}

Research | Update research

post
/research/:id
{
  "id": "123",
  "name": "My new research name"
  "threshold": 200000
}

Header

Field Type Description
Authorization String

Users token.

Path parameters

Field Type Description
id String

Research ID.

Parameter

Field Type Description
name String

New research name.

threshold optional Number

New threshold.

HTTP/1.1 200 OK
{
  "type": "success",
  "handler": "success_topic_updated"
}

Query

Query | Add query

post
/research/:id/query/:query_id
    {
  "name": "test fra",
  "custom_color": "#b6d957",
  "sources": {
    "facebook": {
      "query": {
        "page": [
          {
            "type": "page",
            "owned": true,
            "value": "Abcdef",
            "id": "106805978685897"
          }
        ]
      },
      "text": "Abcdef(pages)"
    },
    "fbGroups": {
      "query": {
        "groups": [
          {
            "type": "group",
            "value": "https://www.facebook.com/groups/dizzymonogatari/"
          }
        ],
        "queries": [
          377
        ]
      },
      "text": "https://www.facebook.com/groups/dizzymonogatari/"
    }
  },
  "additionalSources": true
}

Header

Field Type Description
Authorization String

Users token.

Path parameters

Field Type Description
id String

Topic ID.

query_id optional String

Add new query if omitted, otherwise update the query with the provided ID.

Parameter

Field Type Description
name String

Query name.

custom_color String

Color.

sources Object

Query in array format to be edited in basic editor.

additionalSources Boolean

Enable additional sources.

HTTP/1.1 200 OK
{
  "type": "success",
  "handler": "success_add_query",
  "value": {
    "id": 123,
    "name": "My query name"
  }
}

Query | Delete query

delete
/research/:id/query/:query_id

Header

Field Type Description
Authorization String

Users token.

Path parameters

Field Type Description
id String

Topic ID

query_id String

Query ID

HTTP/1.1 200 OK
{
  "type": "success",
  "handler": "success_delete_query"
}

Query | Validate query

post
/topic/:social/query/validate
{
  "text": "( kpi6 AND social )",
}

Header

Field Type Description
Authorization String

Users token.

Path parameters

Field Type Description
social String

Social.

Allowed values: twitter, webdata

Parameter

Field Type Description
text String

The query to validate.

HTTP/1.1 200 OK
{
  "type": "success",
  "handler": "success_validate_query",
  "value": {
    "valid": true
  }
}
HTTP/1.1 500 Internal Server Error
{
  "type": "error",
  "handler": "error_validate_query",
  "value": {
    "index": 10,
    "description": "Unexpected \"!\""
  }
}

Insights

Insights | Posts

post
/research/:id/posts
{
  "topic_id": "123",
}

Header

Field Type Description
Authorization String

Users token.

Path parameters

Field Type Description
id String

Research ID.

Parameter

Field Type Description
filters optional Object

The filters' data.

order_type optional String

Order method.

Default value: desc

Allowed values: desc, asc

pag optional Number

Pagination.

Default value: 0

perpag optional Number

Results per page.

Default value: 20

Allowed values: 1..500

Twitter parameters only

Field Type Description
order_by optional String

Order by.

Default value: created_at

Allowed values: created_at, username, followers, shares, engagement, posts, sentimentpos, sentimentneg

groupByUser optional Boolean

if true, return one interaction per user.

Default value: false

Instagram parameters only

Field Type Description
order_by optional String

Order by.

Default value: created_at

Allowed values: created_at, comments, engagement, followers, likes, posts, username, sentimentpos, sentimentneg

groupByUser optional Boolean

if true, return one interaction per user.

Default value: false

Facebook parameters only

Field Type Description
order_by optional String

Order by.

Default value: created_at

Allowed values: created_at, likes, shares, comments, engagement, reactions_love, reactions_wow, reactions_haha, reactions_sad, reactions_angry, sentimentpos, sentimentneg

type optional String

Post type.

Default value: posts

Allowed values: posts, comments

include_comments optional Number

Number of comments to return for each post.

Default value: 0

Allowed values: 1..200

WebData parameters only

Field Type Description
order_by optional String

Order by.

Default value: created_at

Allowed values: created_at, comments, shares, participants, engagement, sentimentpos, sentimentneg

HTTP/1.1 200 OK
{
  "type": "success",
  "handler": "success_listening",
  "value": [
    {
      "social": String,
      "id": String,
      "is_comment": Boolean,
      "user": {
        "id": String,
        "username": String,
        "name": String,
        "profile_picture": String,
        "verified": Number,
        "bio": String,
        "category": [String]
      },
      "text": String,
      "link": String,
      "mentions": [String],
      "hashtags": [String],
      "media": [
        {
          "type": String,
          "url": String,
          "title": String,
          "description": String,
          "image": String,
          "labels": [String]
        }
      ],
      "date": {
        "created_at": Datetime
      },
      "sentiment": {
        "value": Number,
        "source": String
      },
      "emotion": {
        "joy": Number,
        "admiration": Number,
        "sadness": Number,
        "fear": Number,
        "anger": Number,
        "disapproval": Number,
        "surprise": Number,
        "smirk": Number,
        "boredom": Number,
        "source": String
      },
      "counts": {
        "following": Number,
        "followers": Number,
        "shares": Number,
        "posts": Number,
        "comments": Number,
        "participants": Number,
        "likes": Number,
        "reactions": {
          "love": Number,
          "wow": Number,
          "haha": Number,
          "sad": Number,
          "angry": Number
        }
      },
      "score": {
        "engagement": Float
      },
      "type": String,
      "comments": [],
      "cml": {...}
    },
    ...
  ]
}

Insights | Category

post
/research/:id/category
{
  "topic_id": "123",
  "based_on": "posts"
}

Header

Field Type Description
Authorization String

Users token.

Path parameters

Field Type Description
id String

Research ID.

Parameter

Field Type Description
filters optional Object

The filters' data.

limit optional Number

Limit to top results, the remaining will be grouped under "Other".

Default value: 5

Facebook parameters only

Field Type Description
based_on optional String

Based on.

Allowed values: posts, comments

WebData parameters only

Field Type Description
based_on optional String

Based on.

Allowed values: category, type

HTTP/1.1 200 OK
{
  "type": "success",
  "handler": "success_listening",
  "value": {
    "clusters": { // Percentage values 
      "News & Media Website": Number,
      "Media/News Company": Number,
      "Local Service": Number,
      ...
    },
    "counts": { // Absolute values
      "News & Media Website": Number,
      "Media/News Company": Number,
      "Local Service": Number,
      ...
    },
   "perc" : [
     {
       "name": String,
       "weight": Number,
       "perc": Float
     },
     ...
   ]
  }
}

Insights | CML trend

post
/research/:id/cmltrend
{
  "topic_id": "123",
  "interval": "dd"
}

Header

Field Type Description
Authorization String

Users token.

Path parameters

Field Type Description
id String

Research ID.

Parameter

Field Type Description
interval String

Time intervals, days or hours.

Allowed values: dd, hh

filters optional Object

The filters' data.

type optional String

Cml type or deployment id

Default value: broadband

HTTP/1.1 200 OK
{
  "type": "success",
  "handler": "success_listening",
  "value": [
    {
      "rule_id": Number,
      "name": String,
      "data": [ [Timestamp, Number], ... ]
    },
    ...
  ]
}

Insights | Emotion

post
/research/:id/emotion
{
  "topic_id": "123",
}

Header

Field Type Description
Authorization String

Users token.

Path parameters

Field Type Description
id String

Research ID.

Parameter

Field Type Description
threshold optional Number

Minimum confidence threshold.

Default value: 20

Allowed values: 1..99

filters optional Object

The filters' data.

Facebook parameters only

Field Type Description
based_on optional String

Based on.

Default value: posts

Allowed values: posts, comments

HTTP/1.1 200 OK
{
  "type": "success",
  "handler": "success_listening",
  "value": {
    "counts": [
      {
        "source": "classifier",
        "joy": Number,
        "admiration": Number,
        "sadness": Number,
        "fear": Number,
        "anger": Number,
        "disapproval": Number,
        "surprise": Number,
        "smirk": Number,
        "boredom": Number
      },
      {
        "source": "emoji",
        "joy": Number,
        "admiration": Number,
        "sadness": Number,
        "fear": Number,
        "anger": Number,
        "disapproval": Number,
        "surprise": Number,
        "smirk": Number,
        "boredom": Number
      }
    ],
    "clusters": [
      {
        "source": "classifier",
        "joy": Number,
        "admiration": Number,
        "sadness": Number,
        "fear": Number,
        "anger": Number,
        "disapproval": Number,
        "surprise": Number,
        "smirk": Number,
        "boredom": Number
      },
      {
        "source": "emoji",
        "joy": Number,
        "admiration": Number,
        "sadness": Number,
        "fear": Number,
        "anger": Number,
        "disapproval": Number,
        "surprise": Number,
        "smirk": Number,
        "boredom": Number
      }
    ]
  }
}

Insights | Full Dashboard Data

post
/research/:id/fullData
{
  "topic_id": "123",
}

Header

Field Type Description
Authorization String

Users token.

Path parameters

Field Type Description
id String

Research ID.

Parameter

Field Type Description
filters optional Object

The filters' data.

HTTP/1.1 200 OK
{
  "type": "success",
  "handler": "success_listening",
  "value": {
     "posts": Number,
     "users": Number,
     "shares": Number,
     "likes": Number,
     "comments": Number,
     "rank": Number,
     "engagement": Number,
     "hashtags": Number,
     "mentions": Number
   }
}

Insights | Gender

post
/research/:id/gender
{
  "topic_id": "123",
}

Header

Field Type Description
Authorization String

Users token.

Path parameters

Field Type Description
id String

Research ID.

Parameter

Field Type Description
filters optional Object

The filters' data.

HTTP/1.1 200 OK
{
  "type": "success",
  "handler": "success_listening",
  "value": {
    "clusters": { // Percentage values 
      "male": Number,
      "female": Number,
      "unknown": Number
    },
    "counts": { // Absolute values
      "male": Number,
      "female": Number,
      "unknown": Number
    }
  }
}

Insights | Geotag

post
/research/:id/geotag
{
  "topic_id": "123"
}

Header

Field Type Description
Authorization String

Users token.

Path parameters

Field Type Description
id String

Research ID.

Parameter

Field Type Description
filters optional Object

The filters' data.

HTTP/1.1 200 OK
{
  "type": "success",
  "handler": "success_listening",
  "value": [
    {
      "id": String,
      "lat": Number,
      "lng": Number,
      "count": Number,
      "location": String
      "geohash": String
    },
    ...
  ]
}

Insights | Image labels

Prerequisite: Image Recognition

post
/research/:id/imagelabels
{
  "topic_id": "123",
  "based_on": "label"
}

Header

Field Type Description
Authorization String

Users token.

Path parameters

Field Type Description
id String

Research ID.

Parameter

Field Type Description
based_on optional String

Image detection type.

Default value: label

Allowed values: label, logo, landmark, web

filters optional Object

The filters' data.

limit optional Number

Limit of labels returned.

Default value: 20

HTTP/1.1 200 OK
{
  "type": "success",
  "handler": "success_listening",
  "value": [
    {
      "name": String,
      "weight": Number,
      "perc": Float
    },
    ...
  ]
}

Insights | Labels

post
/research/:id/labels
{
  "topic_id": "123"
}

Header

Field Type Description
Authorization String

Users token.

Path parameters

Field Type Description
id String

Research ID.

Parameter

Field Type Description
filters optional Object

The filters' data.

HTTP/1.1 200 OK
{
  "type": "success",
  "handler": "success_listening",
  "value": [
    {
      "rule_id": Number,
      "label_id": Number, // Deprecated, use rule_id instead
      "name": String,
      "label_name": String, // Deprecated, use name instead
      "num": Number,
      "perc": Float,
    },
    ...
  ]
}

Insights | Locations

post
/research/:id/locations
{
  "topic_id": "123"
}

Header

Field Type Description
Authorization String

Users token.

Path parameters

Field Type Description
id String

Research ID.

Parameter

Field Type Description
filters optional Object

The filters' data.

HTTP/1.1 200 OK
{
  "type": "success",
  "handler": "success_listening",
  "value": [
    {
      "id": String,
      "lat": Number,
      "lng": Number,
      "count": Number,
      "location": String
      "geohash": String
    },
    ...
  ]
}

Insights | Overview

post
/research/:id/overview
{
  "topic_id": "123",
}

Header

Field Type Description
Authorization String

Users token.

Path parameters

Field Type Description
id String

Research ID.

Parameter

Field Type Description
filters optional Object

The filters' data.

HTTP/1.1 200 OK
{
  "type": "success",
  "handler": "success_listening",
  "value": {
     "posts": Number,
     "users": Number,
     "shares": Number,
     "likes": Number,
     "comments": Number,
     "rank": Number,
     "engagement": Number,
     "hashtags": Number,
     "mentions": Number
   }
}

Insights | Reactions

post
/research/:id/reactions
{
  "topic_id": "123"
}

Header

Field Type Description
Authorization String

Users token

Path parameters

Field Type Description
id String

Research ID.

Parameter

Field Type Description
filters optional Object

The filters' data.

Facebook parameters only

Field Type Description
based_on optional String

Based on.

Default value: posts

Allowed values: posts, comments

HTTP/1.1 200 OK
{
  "type": "success",
  "handler": "success_listening",
  "value": [
    { "name": String, "weight": Number, "perc": Float },
    { "name": String, "weight": Number, "perc": Float },
    { "name": String, "weight": Number, "perc": Float },
    { "name": String, "weight": Number, "perc": Float },
    { "name": String, "weight": Number, "perc": Float }
  ]
}

Insights | Sentiment trend

post
/research/:id/sentimenttrend
{
  "topic_id": "123",
  "interval": "dd"
}

Header

Field Type Description
Authorization String

Users token.

Path parameters

Field Type Description
id String

Research ID.

Parameter

Field Type Description
interval String

Time intervals, days or hours.

Allowed values: dd, hh

filters optional Object

The filters' data.

Facebook parameters only

Field Type Description
based_on optional String

Based on.

Default value: posts

Allowed values: posts, comments

HTTP/1.1 200 OK
{
  "type": "success",
  "handler": "success_listening",
  "value": [
    {
      "rule_id": Number,
      "label_id": Number, // Deprecated, use rule_id instead
      "name": String,
      "label_name": String, // Deprecated, use name instead
      "data": [ [Timestamp, Number], ... ]
    },
    ...
  ]
}

Insights | Sentiment

post
/research/:id/sentiment
{
  "topic_id": "123",
}

Header

Field Type Description
Authorization String

Users token.

Path parameters

Field Type Description
id String

Research ID.

Parameter

Field Type Description
topic_id String

Topic ID.

threshold optional Number

Neutral size.

Default value: 20

Allowed values: 0..100

filters optional Object

The filters' data.

Facebook parameters only

Field Type Description
based_on optional String

Based on.

Default value: posts

Allowed values: posts, comments

HTTP/1.1 200 OK
{
  "type": "success",
  "handler": "success_listening",
  "value": {
    "clusters": { // Percentage values 
      "positive": Number,
      "negative": Number,
      "neutral": Number,
    },
    "counts": { // Absolute values
      "positive": Number,
      "negative": Number,
      "neutral": Number,
    }
  }
}

Insights | Sentiment score

post
/research/:id/sentimentScore
{
  "topic_id": "123",
}

Header

Field Type Description
Authorization String

Users token.

Path parameters

Field Type Description
id String

Research ID.

Parameter

Field Type Description
neutralSize optional Number

Neutral size.

Default value: 20

Allowed values: 2..98

filters optional Object

The filters' data.

Facebook parameters only

Field Type Description
based_on optional String

Based on.

Default value: posts

Allowed values: posts, comments

HTTP/1.1 200 OK
{
  "type": "success",
  "handler": "success_listening",
  "value": {
    "valuesCount": Number,
    "counts": [
      {
        "count": Number,
        "score": Number,
        "sentiment": String
      }
    ]
  }
}

Insights | Sources

post
/research/:id/sources
{
  "topic_id": "123",
}

Header

Field Type Description
Authorization String

Users token.

Path parameters

Field Type Description
id String

Research ID.

Parameter

Field Type Description
filters optional Object

The filters' data.

based_on optional String

Based on.

Default value: desktopmobile

Allowed values: generators, desktopmobile

HTTP/1.1 200 OK
{
  "type": "success",
  "handler": "success_listening",
  "value": [
    {
      "name": String,
      "weight": Number,
      "perc": Float
    },
    ...
  ]
}
HTTP/1.1 200 OK
{
  "type": "success",
  "handler": "success_listening",
  "value": { 
    "clusters": { // Percentage values 
      "desktop": Number,
      "mobile": Number,
      "other": Number
    },
    "counts": { // Absolute values
      "desktop": Number,
      "mobile": Number,
      "other": Number
    }
  }
}

Insights | Stacked CML trend

post
/research/:id/cmlstacked
{
  "topic_id": "123",
  "interval": "dd"
}

Header

Field Type Description
Authorization String

Users token.

Path parameters

Field Type Description
id String

Research ID.

Parameter

Field Type Description
filters optional Object

The filters' data.

based_on optional String

Result grouped by query and category or by category only.

Default value: query

Allowed values: query, category

type optional String

Cml type or deployment id

Default value: broadband

HTTP/1.1 200 OK
{
  "type": "success",
  "handler": "success_listening",
  "value": {
     "threshold": Number,
     "clusters": {
       "name": String,
       "data": [
         { name: String, key: String, label: String, y: Number }
       ]
     }
   }
    ...
  ]
}

Insights | Time trend

post
/research/:id/timetrend
{
  "topic_id": "123",
  "interval": "dd"
}

Header

Field Type Description
Authorization String

Users token.

Path parameters

Field Type Description
id String

Research ID.

Parameter

Field Type Description
interval String

Time intervals, days or hours.

Allowed values: dd, hh

filters optional Object

The filters' data.

Twitter parameters only

Field Type Description
based_on optional String

Based on.

Default value: posts

Allowed values: posts, likes, followers, shares, engagement

Instagram parameters only

Field Type Description
based_on optional String

Based on.

Default value: posts

Allowed values: posts, comments, likes, followers, engagement

Facebook parameters only

Field Type Description
based_on optional String

Based on.

Default value: posts

Allowed values: posts, comments, likes, shares, engagement

WebData parameters only

Field Type Description
based_on optional String

Based on.

Default value: posts

Allowed values: posts, comments, participants, shares, engagement

HTTP/1.1 200 OK
{
  "type": "success",
  "handler": "success_listening",
  "value": [
    {
      "rule_id": Number,
      "label_id": Number, // Deprecated, use rule_id instead
      "name": String,
      "label_name": String, // Deprecated, use name instead
      "data": [ [Timestamp, Number], ... ]
    },
    ...
  ]
}

Insights | Top users

post
/research/:id/topusers
{
  "topic_id": "123"
}

Header

Field Type Description
Authorization String

Users token.

Path parameters

Field Type Description
id String

Research ID.

Parameter

Field Type Description
filters optional Object

The filters' data.

Twitter parameters only

Field Type Description
based_on optional String

Based on.

Default value: posts

Allowed values: posts, followers, following, likes, shares, engagement, mentions

Instagram parameters only

Field Type Description
based_on optional String

Based on.

Default value: posts

Allowed values: posts, likes, comments, followers, following, engagement, mentions

Facebook parameters only

Field Type Description
based_on optional String

Based on.

Default value: posts

Allowed values: posts, comments

WebData parameters only

Field Type Description
based_on optional String

Based on.

Default value: posts

Allowed values: posts, rank, participants, comments, shares, engagement

HTTP/1.1 200 OK
{
  "type": "success",
  "handler": "success_listening",
  "value": [
    {
      "name": String,
      "weight": Number,
      "perc": Float
    },
    ...
  ]
}

Insights | Top words

post
/research/:id/topwords
{
  "topic_id": "123",
}

Header

Field Type Description
Authorization String

Users token.

Path parameters

Field Type Description
id String

Research ID.

Parameter

Field Type Description
filters optional Object

The filters' data.

minWords optional Number

Minimum number of words in a keyword.

Default value: 1

Allowed values: 1..4

maxWords optional Number

Maximum number of words in a keyword.

Default value: 1

Allowed values: 1..4

Twitter parameters only

Field Type Description
based_on optional String

Based on.

Default value: wordshashtags

Allowed values: wordshashtags, words, hashtags, bio

Instagram parameters only

Field Type Description
based_on optional String

Based on.

Default value: hashtags

Allowed values: hashtags, bio

Facebook parameters only

Field Type Description
based_on optional String

Based on.

Default value: posts

Allowed values: posts, comments

HTTP/1.1 200 OK
{
  "type": "success",
  "handler": "success_listening",
  "value": [
    {
      "name": String,
      "weight": Number,
      "perc": Float
    },
    ...
  ]
}

Insights | Topics and Entities

post
/research/:id/topicsandentities
{
  "topic_id": "123"
}

Header

Field Type Description
Authorization String

Users token.

Path parameters

Field Type Description
id String

Research ID.

Parameter

Field Type Description
limit optional Number

Limit the number of items for each level.

Default value: 15

entities optional Boolean

Return entities list.

HTTP/1.1 200 OK
{
  "type": "success",
  "handler": "success_get_field",
  "value": {
    "series": [
      {
        "name": String,
        "data": Array
      }
    ],
    "drilldown": [
      {
        "id": String
        "name": String,
        "data": Array
      },
      ...
    ]
  }
}

Insights | Users habits

post
/research/:id/usershabits
{
  "topic_id": "123",
}

Header

Field Type Description
Authorization String

Users token.

Path parameters

Field Type Description
id String

Research ID.

Parameter

Field Type Description
filters optional Object

The filters' data.

Twitter parameters only

Field Type Description
based_on optional String

Based on.

Default value: posts

Allowed values: posts, likes, followers, shares, engagement

Instagram parameters only

Field Type Description
based_on optional String

Based on.

Default value: posts

Allowed values: posts, likes, comments, followers, engagement

Facebook parameters only

Field Type Description
based_on optional String

Based on.

Default value: posts

Allowed values: posts, comments

HTTP/1.1 200 OK
{
  "type": "success",
  "handler": "success_listening",
  "value": [
    [ Number (day 0-6), Number (hour 0-23), Number (absolute value), Float (percentage value) ], ...
  ]
}

Filters

Filters | Delete filter

delete
/research/:id/filters/:filter_id
{
  "social": "twitter",
  "id": "123",
  "topic_id": "123"
}

Header

Field Type Description
Authorization String

Users token.

Path parameters

Field Type Description
id String

Research ID.

filter_id String

Filter ID.

topic_id optional String

Topic ID Omit this for shared filters.

HTTP/1.1 200 OK
{
  "type": "success",
  "handler": "success_filters"
}

Filters | Get alert filters

get
/research/:id/filters/crisis

Header

Field Type Description
Authorization String

Users token.

Path parameters

Field Type Description
id String

Research ID.

HTTP/1.1 200 OK
{
  "type": "success",
  "handler": "success_crisis_filters",
  "value": {
    "shared": [...],
    "topic": [...]
  }
}

Filters | Get alert filters

get
/alerts

Header

Field Type Description
Authorization String

Users token.

HTTP/1.1 200 OK
{
  "type": "success",
  "handler": "success_user_crisis",
   "value": {
     "counter": Number,
       "alerts" : {
         "social" : {
           "topic_id" : [
             {
               "filter": { "name": String },
               "topic": { "topic_name": String }
             }, 
             ...
           ]
        }
     }
  }
}

Filters | New filter

post
/research/:id/filters
{
  "social": "twitter",
  "topic_id": "123",
  "name": "My filter name",
  "filters": "sentiment<20 AND gender:male"
}

Header

Field Type Description
Authorization String

Users token.

Path parameters

Field Type Description
id String

Research ID.

Parameter

Field Type Description
name String

Filter name.

filters String

The string with filters.

social String

Social.

Allowed values: twitter, facebook, instagram, webdata

topic_id optional String

Create a shared filter if omitted, otherwise create a filter for the provided research.

id optional String

New filter is created if omitted, otherwise update the filter with the provided ID.

HTTP/1.1 200 OK
{
  "type": "success",
  "handler": "success_filters"
  "value": {
    "id": String,
    "name": String,
    "filters": String
  }
}

Filters | Set alert filter

post
/research/:id/filters/:filter_id/crisis
{
  "id": "123",
  "filter_id" "123",
  "social": "twitter",
  "recipients": [
    { "type": "email", "recipient": "email@example.com" },
    { "type": "phone", "recipient": "+39..." },
    ...
  ]
  "interval": "15m",
  "set": true,
}

Header

Field Type Description
Authorization String

Users token.

Path parameters

Field Type Description
id String

Research ID.

filter_id String

Filter ID.

Parameter

Field Type Description
set Boolean

If true set the filter as alert, unset otherwise.

interval String

Interval time to get notified.

Allowed values: 15m, 1h, 1d, 1w

recipients optional Array

Array of recipients where to send the notifications on each interval.

apiurl optional String

GET URL to call on each interval.

cml optional String

CML field name.

HTTP/1.1 200 OK
{
  "type": "success",
  "handler": "success_filters"
}

Posts

Posts | Update sentiment of posts

post
/research/:id/updateSentiment
{
  "topic_id": "123",
  "post_ids": ["1001607723950202881", "1001607723950202882"],
  "sentiment": 80
}

Header

Field Type Description
Authorization String

Users token.

Path parameters

Field Type Description
id String

Research ID.

Parameter

Field Type Description
post_ids Array

Post IDs.

sentiment Number

Sentiment score to assign to all posts.

Allowed values: 0..100

comment Boolean

Set to true if post_ids are comments.

Allowed values: false

HTTP/1.1 200 OK
{
  "type": "success",
  "handler": "success_sentiment_updated",
  "value": 80
}

AI

AI | Count images for Image Recognition

post
/research/:id/imagerecognition/counts

Header

Field Type Description
Authorization String

Users token.

Path parameters

Field Type Description
id String

Research ID.

Parameter

Field Type Description
filters optional Object

The filters' data.

HTTP/1.1 200 OK
{
  "type": "success",
  "handler": "success_imagerecognition_count",
  "value": {
     "count": {
       "post": Number,
       "profile_picture": Number
     } 
  }
}

AI | Start Image Recognition

post
/research/:id/imagerecognition/start
{
  "topic_id": "123",
  "type": "label"
}

Header

Field Type Description
Authorization String

Users token.

Path parameters

Field Type Description
id String

Research ID.

Parameter

Field Type Description
type optional String

Image recognition type

Default value: label

Allowed values: label, landmark, logo, web

image_source optional String

Image source: post or profile_picture

Default value: post

Allowed values: post, profile_picture

filters optional Object

The filters' data.

HTTP/1.1 200 OK
{
  "type": "success",
  "handler": "success_imagerecognition",
  "value": {
     "job": {
       "queue": String,
       "job_id": Number
     } 
  }
}

AI | Toggle AI

post
/research/:id/ai/enable
{
  "topic_id": "123",
  "type": "sentimentEmotion"
  "enable": true
}

Header

Field Type Description
Authorization String

Users token.

Path parameters

Field Type Description
id String

Research ID.

Twitter parameters only

Field Type Description
type String

AI type.

Allowed values: sentimentEmotion, gender, topicsAndEntities

Instagram parameters only

Field Type Description
type String

AI type.

Allowed values: sentimentEmotion, gender, topicsAndEntities

Facebook parameters only

Field Type Description
type String

AI type.

Allowed values: sentimentEmotion, sentimentEmotionComments, topicsAndEntities

WebData parameters only

Field Type Description
type String

AI type.

Allowed values: sentimentEmotion

Parameter

Field Type Description
enable Boolean

Enabled status.

 HTTP/1.1 200 OK
{
  "type": "success",
  "handler": "success_ai_updated",
  "value": {
    "sentimentEmotion": true,
    "gender": true
  }
}

Audiences

Audiences | Add filter

post
/audiences/lists/:id/filter
{
  type: "entities",
  filter: ["Donald Trump", "Vladimir Putin"]
}

Header

Field Type Description
Authorization String

Users token

Path parameters

Field Type Description
id String

Audience ID

Parameter

Field Type Description
type String

Filter type

Allowed values: entities

filter Array

Filter

HTTP/1.1 200 OK
{
  "type": "success",
  "handler": "success_audiences_filter",
  "value": {
     "filter": {
         "entities": ["Donald Trump", "Vladimir Putin"]
      }
   }
}

Audiences | Add followers of a user into a new audience

Start the extraction of the followers into an audience.

post
/audiences/lists/addFollowers
{
  "list_id": "123",
  "user_ids": [456]
}

Header

Field Type Description
Authorization String

Users token

Parameter

Field Type Description
list_id String

Audience ID.

user_ids String[]

Array of user_ids to add (max 1, Twitter only).

num_followers Number

Number of followers to get.

Allowed values: 1..500

HTTP/1.1 200 OK
{
  "type": "success",
  "handler": "success_audiences"
}

Audiences | Add users into an audience

post
/research/:id/audiences/:list_id/addUsers
{
  "list_id": "123"
  "topic_id": "123",
  "social": "twitter"
}

Header

Field Type Description
Authorization String

Users token

Path parameters

Field Type Description
id String

Research ID.

list_id String

Audience ID.

Parameter

Field Type Description
social String

Social.

Allowed values: twitter, instagram, facebook

filters optional Object

Filter data.

HTTP/1.1 200 OK
{
  "type": "success",
  "handler": "success_audiences_extract"
}

Audiences | Clone audience

post
/audiences/lists/clone
{
  "list_id": "123",
  "name": "Cloned audience"
}

Header

Field Type Description
Authorization String

Users token

Parameter

Field Type Description
list_id String

Audience ID.

name String

Cloned audience name.

HTTP/1.1 200 OK
{
  "type": "success",
  "handler": "success_audiences"
}

Audiences | Delete audience users

post
/audiences/lists/:id/users
{
  "user_ids": ["123", "456", "789", ...]
}

Header

Field Type Description
Authorization String

Users token

Path parameters

Field Type Description
id String

Audience ID.

Parameter

Field Type Description
user_ids String[]

Array of user_ids to delete.

HTTP/1.1 200 OK
{
  "type": "success",
  "handler": "success_audiences"
}

Audiences | Delete audience

delete
/audiences/lists/:id

Header

Field Type Description
Authorization String

Users token

Path parameters

Field Type Description
id String

Audience ID

HTTP/1.1 200 OK
{
  "type": "success",
  "handler": "success_audiences"
}

Audiences | Enable research audience

post
/research/:id/audiences
{
  "enrichments": ['pi', 'interests', 'demographics', 'jobtitles']
}

Header

Field Type Description
Authorization String

Users token

Path parameters

Field Type Description
id String

Research ID.

Parameter

Field Type Description
enable Boolean

Enable audience

Allowed values: false

enrichments Array

Enrichments to apply

HTTP/1.1 200 OK
{
  "type": "success",
  "handler": "success_audiences_enable"
}

Audiences | Enrich audience

post
/audiences/enrich
{
  "list_id": "123",
  "type": "interests"
}

Header

Field Type Description
Authorization String

Users token

Parameter

Field Type Description
list_id String

Audience ID.

type String

Enrich type.

Allowed values: interests, pi, demographics, jobtitles

user_ids optional String[]

Array of user_ids to enrich.

HTTP/1.1 200 OK
{
  "type": "success",
  "handler": "success_audiences"
}

Audiences | Get audience user

get
/audiences/lists/:list_id/user/:user_id

Header

Field Type Description
Authorization String

Users token

Path parameters

Field Type Description
list_id String

Audience ID

user_id String

User ID

HTTP/1.1 200 OK
{
  "type": "success",
  "handler": "success_audiences",
  "value": {
    "user_id": Number,
    "social_userid": String,
    "social": String,
    "username": String,
    "name": String,
    "profile_picture": String,
    "bio": String,
    "lang": String,
    "gender": String,
    "age": String,
    "created_at": Date,
    "following": Number,
    "followers": Number,
    "posts": Number,
    "list_id": Number,
    "avg_posts": Number,
    "avg_likes": Number,
    "avg_engagement": Number,
    "interests_tree": {
      "series": [
        {
          "name": String,
          "data": Array
        }
      ],
      "drilldown": [
        {
          "id": String
          "name": String,
          "data": Array
        },
        ...
      ]
    }
    "interests": [
      {
        "user_id": Number,
        "name": String,
        "value": String,
        "extras": String
      }
    ],
    "pi": [
      {
        "user_id": Number,
        "name": String,
        "value": String,
        "extras": String
      }
    ]
  }
}

Audiences | Get audience users

post
/audiences/lists/users
{
  "list_id": "123"
}

Header

Field Type Description
Authorization String

Users token

Parameter

Field Type Description
list_id String

Audience ID.

pag optional Number

Pagination. Use -1 to prevent pagination.

perpag optional Number

Result per page.

Default value: 20

Allowed values: 1..100

orderby optional String

Order by parameter.

Default value: username

Allowed values: age, avg_posts, avg_engagement, created_at, ffratio, followers, gender, lang, username

ordertype optional String

Order type parameter.

Default value: asc

Allowed values: asc, desc

search optional String

Search parameter.

Allowed values: age, avg_posts, avg_engagement, bio, email, followers, ffratio, gender, interest, job_title, lang, name, social, username

csv optional Boolean

If true, return the users in CSV format.

HTTP/1.1 200 OK
{
  "type": "success",
  "handler": "success_audiences",
  "value": {
    "data": [
      {
        "user_id": Number,
        "social_userid": String,
        "social": String,
        "username": String,
        "name": String,
        "profile_picture": String,
        "email": String,
        "bio": String,
        "lang": String,
        "gender": String,
        "age": String,
        "job_title": String,
        "created_at": Date,
        "following": Number,
        "followers": Number,
        "posts": Number,
        "avg_posts": Float,
        "avg_engagement": Float,
        "ffratio": Float,
        "enrich": {
          "interest": [...],
          ...
        }
      },
      ...
    ],
    "total": Number,
    "totalWithFeed": Number,
    "totalWithFeedPerc": Float
  }
}

Audiences | Get audience

get
/audiences/lists/:id

Header

Field Type Description
Authorization String

Users token

Path parameters

Field Type Description
id String

Audience ID

HTTP/1.1 200 OK
{
  "type": "success",
  "handler": "success_audiences",
  "value": { 
    "list_id": Number,
    "name": String,
    "username": String,
    "status": String,
    "created_at": Date,
    "info": String
  }
}

Audiences | Get audiences

get
/audiences/lists

Header

Field Type Description
Authorization String

Users token.

HTTP/1.1 200 OK
{
  "type": "success",
  "handler": "success_audiences",
  "value": [
    {
      "list_id": Number,
      "name": String,
      "username": String,
      "status": String,
      "created_at": Date,
      "info": {
        "topic_id": {
          "topic_name": String,
          "social": String,
          "filter_name": String
        }
      },
      "users_count": Number,
      "event_history": [
        {
          "event": "creation",
          "timestamp": 1644586423
        },
        ...
      ]
    },
    ...
  ]
}

Audiences | Get user feed

post
/audiences/user/feed
{
  "user_id": "123"
  "social": "twitter"
}

Header

Field Type Description
Authorization String

Users token

Parameter

Field Type Description
user_id Number

User ID

social String

Social

Allowed values: twitter, instagram, facebook

HTTP/1.1 200 OK
{
  "type": "success",
  "handler": "success_audiences",
  "value": [
    {
      "user_id": Number,
      "id": Number,
      "created_at": Timestamp,
      "text": String,
      "likes": Number,
      "comments": Number,
      "image": String,
      "social": String,
    },
    ...
  ]
}

Audiences | New audience

post
/audiences/lists
{
  "name": "My audience name"
}

Header

Field Type Description
Authorization String

Users token

Parameter

Field Type Description
name String

Name of the new audience

HTTP/1.1 200 OK
{
  "type": "success",
  "handler": "success_audiences"
  "value": 1234
}

Audiences | Populate audience

post
/audiences/lists/:id/populate
{
  "gender": ['male'],
  "age_range": [30, 40],
  "languages": ['it', 'fr', 'en'],
  "interests": ['sports', 'automotive', ...]
}

Header

Field Type Description
Authorization String

Users token

Path parameters

Field Type Description
id String

Audience ID.

Parameter

Field Type Description
gender optional Object

Gender.

Number[]

[age_range] min and max Age.

String[]

[languages] list of Languages.

HTTP/1.1 200 OK
{
  "type": "success",
  "handler": "success_populate_audience"
}

Audiences | Search audience user

post
/audiences/lists/search
{
  "username": "anasciuti"
}

Header

Field Type Description
Authorization String

Users token

Parameter

Field Type Description
name String

First name and/or last name (required if no username is specified).

username String

Username (required if no name is specified).

social optional String

Social.

Allowed values: twitter, instagram, facebook

bio optional String

Biography contains.

lang optional String

Language: ISO 639-1 standard. Examples: "it", "en".

gender optional String

Gender.

Allowed values: male, female, unknown

followers optional Number

Minimum number of followers.

following optional Number

Minimum number of following.

posts optional Number

Minimum number of posts.

HTTP/1.1 200 OK
{
  "type": "success",
  "handler": "success_audiences",
  "value": [
    {
      "social": String,
      "username": String,
      "name": String,
      "profile_picture": String,
      "bio": String,
      "lang": String,
      "gender": String,
      "following": Number,
      "followers": Number,
      "posts": Number
    },
    ...
  ]
}

Audiences | Share audience

post
/audiences/lists/:id/share
{
  "email": "user@kpi6.com",
  "permissions": [
     "get_audiences"
   ]
}

Header

Field Type Description
Authorization String

Users token

Path parameters

Field Type Description
id String

Audience ID

Audiences | Update audience user

put
/audiences/user

Header

Field Type Description
Authorization String

Users token

Parameter

Field Type Description
list_id Number

Audience ID

user_id Number

User ID

type String

Field type

Allowed values: gender, lang

value String

Field value

HTTP/1.1 200 OK
{
  "type": "success",
  "handler": "success_audiences"
}

Audiences | Update audience

post
/audiences/lists/update
{
  "list_id": "123",
  "name": "My new audience name"
}

Header

Field Type Description
Authorization String

Users token

Parameter

Field Type Description
list_id String

Audience ID

name String

New name of the audience

HTTP/1.1 200 OK
{
  "type": "success",
  "handler": "success_audiences"
}

Twitter

Twitter | Get Twitter user

post
/twitter/userinfo
{
  "username": "kpi6com"
}

Header

Field Type Description
Authorization String

Users token.

Parameter

Field Type Description
id optional String

ID of the user (Required if username is omitted).

username optional String

Username of the user (Required if id is omitted).

HTTP/1.1 200 OK
{
  "type": "success",
  "handler": "success_tw_info",
  "value": 
  "value": {
    "id": Number,
    "id_str": String,
    "name": String,
    "screen_name": String,
    "location": String,
    "profile_location": String,
    "description": String,
    "url": String,
    "entities": { ... },
    "protected": Boolean,
    "followers_count": Number,
    "friends_count": Number,
    "listed_count": Number,
    "created_at": Date,
    "favourites_count": Number,
    "utc_offset": String,
    "time_zone": String,
    "geo_enabled": Boolean,
    "verified": Boolean,
    "statuses_count": Number,
    "lang": String,
    "contributors_enabled": Boolean,
    "is_translator": Boolean,
    "is_translation_enabled": Boolean,
    "profile_background_color": String,
    "profile_background_image_url": String,
    "profile_background_image_url_https": String,
    "profile_background_tile": Boolean,
    "profile_image_url": String,
    "profile_image_url_https": String,
    "profile_banner_url": String,
    "profile_link_color": String,
    "profile_sidebar_border_color": String,
    "profile_sidebar_fill_color": String,
    "profile_text_color": String,
    "profile_use_background_image": Boolean,
    "has_extended_profile": Boolean,
    "default_profile": Boolean,
    "default_profile_image": Boolean,
    "following": Boolean,
    "follow_request_sent": Boolean,
    "notifications": Boolean,
    "translator_type": String
  }
}

Twitter | Search for Twitter users

post
/topic/twitter/search
{
  "q": "kpi6"
}

Header

Field Type Description
Authorization String

Users token.

Parameter

Field Type Description
q String

Search query.

HTTP/1.1 200 OK
{
  "type": "success",
  "handler": "success_tw_search",
  "value": {
    "username": String,
    "name": String,
    "profile_pic": String,
    "followers": Integer,
    "created_at": Date,
    "verified": Boolean,
    "lang": String,
    "id": String,
  }

Instagram

Instagram | Get Instagram user

post
/instagram/userinfo
{
  "username": "kpi6com"
}

Header

Field Type Description
Authorization String

Users token.

Parameter

Field Type Description
id optional String

ID of the user (Required if username is omitted).

username optional String

Username of the user (Required if id is omitted).

HTTP/1.1 200 OK
{
  "type": "success",
  "handler": "success_ig_info",
  "value": {
    "id": String,
    "full_name": String,
    "profile_picture": String,
    "username": String,
    "bio": String,
    "counts": {
      "follows": Number,
      "followed_by": Number,
      "media": Number
    },
    "website": String
  }
}

Instagram | Search for Instagram business or creator account

Returns info about an Instagram business or creator account.

post
/topic/instagram/business_discovery
{
  "username": "username",
}

Header

Field Type Description
Authorization String

Users token

HTTP/1.1 200 OK
{
  "type": "success",
  "handler": "success_business_discovery",
  "value": { id: '123',
             name: 'account name',
             username: 'username',
             profile_picture_url: uri,
             biography: 'biography'
            }
}

Instagram | Search for recently used instagram hashtags

Returns a list of hashtags searched in the last 7 days.

get
/topic/instagram/recent_hashtags

Header

Field Type Description
Authorization String

Users token

HTTP/1.1 200 OK
{
  "type": "success",
  "handler": "success_business_discovery",
  "value": [{ id: '123',
             name: 'hashtag',
            }, ...]
}

Instagram | Search for Instagram hashtag, user or place

post
/topic/instagram/search
{
  "type": "place",
  "q": "Milan",
  "business": false
}

Header

Field Type Description
Authorization String

Users token.

Parameter

Field Type Description
type String

Search type.

Allowed values: hashtag, user, place

q String

Search query.

business Boolean

Enables instagram business hashtag search.

HTTP/1.1 200 OK
{
  "type": "success",
  "handler": "success_ig_search",
  "value": [
     {
       "id": String,
       "name": String,
       "media_count": Number,
       "search_result_subtitle": String
     },
     ...
  ]
}
HTTP/1.1 200 OK
{
  "type": "success",
  "handler": "success_ig_search",
  "value": [
     {
       "id": String,
       "name": String,
       "username": String,
       "is_private": Boolean,
       "is_verified": Boolean,
       "profile_pic_url": String
     },
     ...
  ]
}
HTTP/1.1 200 OK
{
  "type": "success",
  "handler": "success_ig_search",
  "value": [ 
     {
       "id": String,
       "name": String,
       "latitude": Float,
       "longitude": Float
     }, 
     ... 
  ]
}

Facebook

Facebook | Get Facebook page categories

get
/facebook-categories

Header

Field Type Description
Authorization String

Users token.

HTTP/1.1 200 OK
{
  "type": "success",
  "handler": "success_facebook_categories",
  "value": [{
    "group": "Interest",
    "categories": [
      "Literary Arts",
      "Performance Art",
      "Performing Arts",
      "Science",
      "Sports",
      "Visual Arts"
    ]
  },
  { ... }
 ]
}

Facebook | Get Facebook page

post
/facebook/pageinfo
{
  "username": "kpi6com"
}

Header

Field Type Description
Authorization String

Users token.

Parameter

Field Type Description
id optional String

ID of the Facebook page (Required if username is omitted).

username optional String

Username of the Facebook page (Required if id is omitted).

HTTP/1.1 200 OK
{
  "type": "success",
  "handler": "success_fb_info",
  "value": {
    "id": String,
    "type": String,
    "place_type": String,
    "username": String,
    "name": String,
    "parent_page": String,
    "global_brand_id": String,
    "link": String,
    "picture": String,
    "cover": String,
    "featured_video": String,
    "about": String,
    "description": String,
    "company_overview": String,
    "mission": String,
    "personal_info": String,
    "personal_interests": String,
    "displayed_message_response_time": String,
    "category": String,
    "website": String,
    "emails": String,
    "phone": String,
    "whatsapp_number": String,
    "founded": String,
    "birthday": String,
    "is_chain": Boolean,
    "is_owned": v,
    "is_unclaimed": Boolean,
    "verification_status": String,
    "engagement": Number,
    "checkins_count": Number,
    "rating_count": Number,
    "overall_star_rating": Number,
    "talking_about_count": Number,
    "were_here_count": Number,
    "price_range": String,
    "place_id": String,
    "place_name": String,
    "location_city": String,
    "location_country": String,
    "location_latitude": Number,
    "location_longitude": Number,
    "location_street": String,
    "location_zip": String,
    "updated_time": Date,
    "updated_at": Date,
    "last_post_scraping_at": Date
  }
}

Facebook | Search Facebook page

Requires Facebook account

post
/topic/facebook/search
{
  "type": "page",
  "q": "Nike"
}

Header

Field Type Description
Authorization String

Users token.

Parameter

Field Type Description
type String

Search type.

Allowed values: page

q String

Page username or page URL.

HTTP/1.1 200 OK
{
  "type": "success",
  "handler": "success_fb_search",
  "value": [
    {
      "name": String,
      "id": String,
      "profile_picture": String,
      "link": String,
      "about": String,
      "category": String,
      "type": String,
      "engagement": {
        "count": Number,
        "social_sentence": String
      },
      "verification_status": String,
      "location": {
        "city": String,
        "country": String,
        "state": String,
        "street": String,
        "zip": String
      },
      "talking_about_count": Number
    },
    ...
  ]
}

Webdata

Webdata | Get posts preview

Get the 100 most recent posts for a query

post
/topic/webdata/preview/posts
{
  "topic_id": "123",
  "text": "( kpi6 AND social )",
  "start": 1517097600000,
}

Header

Field Type Description
Authorization String

Users token.

Parameter

Field Type Description
topic_id String

Topic ID.

text String

Rule text.

start Timestamp

Start date.

HTTP/1.1 200 OK
{
  "type": "success",
  "handler": "success_webdata",
  "value": {
    "posts": [
      {
        "id": String,
        "link": String,
        "title": String,
        "created_at": Date,
        "text": String,
        "author": String,
        "site": String,
        "type": String,
        "section_title": String,
        "site_categories": String
      },
      ...
    ],
    "query": { 
      "text": String,
      "parameters": { ...} 
    },
    "top_words": [
      {
        "name": String,
        "weight": Number,
        "perc": Float
      },
      ...
    ]
  }
}

Webdata | Get preview counts

post
/topic/webdata/preview/counts
{
  "topic_id": "123",
  "text": "( kpi6 AND social )",
  "start": 1514761200000
  "end": 1525039200000
}

Header

Field Type Description
Authorization String

Users token.

Parameter

Field Type Description
topic_id String

Topic ID.

rule_id String

Label ID.

text String

Rule text.

start Timestamp

Start date.

end Timestamp

End date.

HTTP/1.1 200 OK
{
  "type": "success",
  "handler": "success_counts",
    "value": {
      "costInUSD": Number,
      "estimatedTotalPostCount": Number,
      "confirmationToken": String,
      "rule_id": Number,
      "backlog": {
        "costInUSD": Boolean,
        "estimatedTotalPostCount": Number,
        "estimatedPerDay": [
          Number,
          ...
        ],
        "confirmationToken": Boolean
      }
    }
  }
}

Webdata | Get Webdata site categories

Get webdata categories list

get
/webdata-categories

Header

Field Type Description
Authorization String

Users token.

HTTP/1.1 200 OK
{
  "type": "success",
  "handler": "success_webdata_categories",
  "value": [{
    "group": "Categories",
    "categories": [
      String
    ]
  }, 
  { ... }
 ]
}

Audiences Insights

Audiences Insights | Age by Gender

post
/audiences/users/age_by_gender
{
  "list_id": "123"
}

Header

Field Type Description
Authorization String

Users token

Parameter

Field Type Description
list_id String

Audience ID.

word optional String

Filter results by word.

bio optional String

Filter results by biography word.

jobtitle optional String

Filter results by job title.

age optional String

Filter results by gender.

gender optional String

Filter results by gender.

interest optional String

Filter results by interest.

lang optional String

Filter results by language.

country optional String

Filter results by country.

audience_location optional String

Filter results by user place.

HTTP/1.1 200 OK
{
  "type": "success",
  "handler": "success_audiences",
  "value":
    {
      "18-24": {
         "male": { "y": 20, "perc": 10% }
         "female": { "y": 18, "perc": 9% }
       },
      "25-34": {
         "unknown": { ... }
       },
      ...
    }
}

Audiences Insights | Age

post
/audiences/users/age
{
  "list_id": "123"
}

Header

Field Type Description
Authorization String

Users token

Parameter

Field Type Description
list_id String

Audience ID.

based_on optional String

Aggregation type [ageRange, generations].

word optional String

Filter results by word.

bio optional String

Filter results by biography word.

jobtitle optional String

Filter results by job title.

gender optional String

Filter results by gender.

interest optional String

Filter results by interest.

lang optional String

Filter results by language.

country optional String

Filter results by country.

audience_location optional String

Filter results by user place.

HTTP/1.1 200 OK
{
  "type": "success",
  "handler": "success_audiences",
  "value": [
    {
      "name": String,
      "weight": Number,
      "perc": Float
    },
    ...
  ]
}

Audiences Insights | Countries

post
/audiences/users/country
{
  "list_id": "123"
}

Header

Field Type Description
Authorization String

Users token

Parameter

Field Type Description
list_id String

Audience ID

max optional Number

Max items to show.

Default value: 6

word optional String

Filter results by word.

bio optional String

Filter results by biography word.

jobtitle optional String

Filter results by job title.

age optional String

Filter results by age range.

gender optional String

Filter results by gender.

lang optional String

Filter results by language.

interest optional String

Filter results by interest.

audience_location optional String

Filter results by user place.

HTTP/1.1 200 OK
{
  "type": "success",
  "handler": "success_audiences",
  "value": [
    {
      "name": String,
      "weight": Number,
      "perc": Float
    },
    ...
  ]
}

Audiences Insights | Gender

post
/audiences/users/gender
{
  "list_id": "123"
}

Header

Field Type Description
Authorization String

Users token

Parameter

Field Type Description
list_id String

Audience ID.

word optional String

Filter results by word.

bio optional String

Filter results by biography word.

jobtitle optional String

Filter results by job title.

age optional String

Filter results by age range.

interest optional String

Filter results by interest.

lang optional String

Filter results by language.

country optional String

Filter results by country.

audience_location optional String

Filter results by user place.

HTTP/1.1 200 OK
{
  "type": "success",
  "handler": "success_audiences",
  "value": {
    "clusters": { // Percentage values
      "male": Number,
      "female": Number,
      "unknown":Number
    },
    "counts": { // Absolute values
      "male": Number,
      "female": Number,
      "unknown": Number
    }
  }
}

Audiences Insights | Interests tree

post
/audiences/users/intereststree
{
  "list_id": "123"
}

Header

Field Type Description
Authorization String

Users token

Parameter

Field Type Description
list_id String

Audience ID

index optional String

Average index to use

Default value: offset

Allowed values: offset, affinity

limit optional Number

Limit the number of items for each level

Default value: 15

lang optional String

Filter results by language.

country optional String

Filter results by country.

gender optional String

Filter results by gender.

age optional String

Filter results by age range.

word optional String

Filter results by word.

entities optional Boolean

Return entities list.

audience_location optional String

Filter results by user place.

HTTP/1.1 200 OK
{
  "type": "success",
  "handler": "success_audiences",
  "value": {
    "series": [
      {
        "name": String,
        "data": Array
      }
    ],
    "drilldown": [
      {
        "id": String
        "name": String,
        "data": Array
      },
      ...
    ]
  }
}

Audiences Insights | Interests

post
/audiences/users/interests
{
  "list_id": "123"
}

Header

Field Type Description
Authorization String

Users token

Parameter

Field Type Description
list_id String

Audience ID

lang optional String

Filter results by language.

country optional String

Filter results by country.

gender optional String

Filter results by gender.

age optional String

Filter results by age range.

word optional String

Filter results by word.

audience_location optional String

Filter results by user place.

limit optional Number

Limit number of results.

Default value: 100

HTTP/1.1 200 OK
{
  "type": "success",
  "handler": "success_audiences",
  "value": [
    {
      "name": String,
      "weight": Number,
      "perc": Float
    },
    ...
  ]
}

Audiences Insights | Interests

post
/audiences/users/interests
{
  "list_id": "123"
}

Header

Field Type Description
Authorization String

Users token

Parameter

Field Type Description
list_id String

Audience ID

lang optional String

Filter results by language.

country optional String

Filter results by country.

gender optional String

Filter results by gender.

age optional String

Filter results by age range.

word optional String

Filter results by word.

audience_location optional String

Filter results by user place.

limit optional Number

Limit number of results.

Default value: 100

HTTP/1.1 200 OK
{
  "type": "success",
  "handler": "success_audiences",
  "value": [
    {
      "name": String,
      "weight": Number,
      "perc": Float
    },
    ...
  ]
}

Audiences Insights | Job titles

post
/audiences/users/jobtitles
{
  "list_id": "123"
}

Header

Field Type Description
Authorization String

Users token

Parameter

Field Type Description
list_id Number

Audience ID.

lang optional String

Filter results by language.

country optional String

Filter results by country.

interest optional String

Filter results by interest.

bio optional String

Filter results by bio word.

gender optional String

Filter results by gender.

age optional String

Filter results by age.

audience_location optional String

Filter results by user place.

limit optional Number

Limit number of results.

Default value: 100

HTTP/1.1 200 OK
{
  "type": "success",
  "handler": "success_audiences",
  "value": [
    {
      "name": String,
      "weight": Number,
      "perc": Float
    },
    ...
  ]
}

Audiences Insights | Languages

post
/audiences/users/language
{
  "list_id": "123"
}

Header

Field Type Description
Authorization String

Users token

Parameter

Field Type Description
list_id String

Audience ID

max optional Number

Max items to show.

Default value: 6

word optional String

Filter results by word.

bio optional String

Filter results by biography word.

jobtitle optional String

Filter results by job title.

age optional String

Filter results by age range.

gender optional String

Filter results by gender.

country optional String

Filter results by country.

interest optional String

Filter results by interest.

audience_location optional String

Filter results by user place.

HTTP/1.1 200 OK
{
  "type": "success",
  "handler": "success_audiences",
  "value": [
    {
      "name": String,
      "weight": Number,
      "perc": Float
    },
    ...
  ]
}

Audiences Insights | Personality traits

post
/audiences/users/pi
{
  "list_id": "123"
}

Header

Field Type Description
Authorization String

Users token

Parameter

Field Type Description
list_id String

Audience ID

lang optional String

Filter results by language.

country optional String

Filter results by country.

gender optional String

Filter results by gender.

age optional String

Filter results by age range.

audience_location optional String

Filter results by user place.

HTTP/1.1 200 OK
{
  "type": "success",
  "handler": "success_audiences",
  "value": {...}
}

Audiences Insights | Sentiment

post
/audiences/users/sentiment
{
  "list_id": "123"
}

Header

Field Type Description
Authorization String

Users token

Parameter

Field Type Description
list_id String

Audience ID

lang optional String

Filter results by language.

country optional String

Filter results by country.

gender optional String

Filter results by gender.

age optional String

Filter results by age range.

audience_location optional String

Filter results by user place.

HTTP/1.1 200 OK
{
  "type": "success",
  "handler": "success_audiences",
  "value": {...}
}

Audiences Insights | Top biography words and mentions

post
/audiences/users/topbiowords
{
  "list_id": "123"
}

Header

Field Type Description
Authorization String

Users token

Parameter

Field Type Description
list_id Number

Audience ID.

lang optional String

Filter results by language.

country optional String

Filter results by country.

interest optional String

Filter results by interest.

gender optional String

Filter results by gender.

age optional String

Filter results by age.

audience_location optional String

Filter results by user place.

limit optional Number

Limit number of results.

Default value: 50

minWords optional Number

Minimum number of words in a keyword.

Default value: 1

Allowed values: 1..4

maxWords optional Number

Maximum number of words in a keyword.

Default value: 1

Allowed values: 1..4

HTTP/1.1 200 OK
{
  "type": "success",
  "handler": "success_audiences",
  "value": [
    {
      "name": String,
      "weight": Number,
      "perc": Float,
      "type": String
    },
    ...
  ]
}

Audiences Insights | Top words and mentions

post
/audiences/users/topwords
{
  "list_id": "123"
}

Header

Field Type Description
Authorization String

Users token

Parameter

Field Type Description
list_id Number

Audience ID.

lang optional String

Filter results by language.

country optional String

Filter results by country.

interest optional String

Filter results by interest.

gender optional String

Filter results by gender.

age optional String

Filter results by age.

audience_location optional String

Filter results by user place.

limit optional Number

Limit number of results.

Default value: 50

minWords optional Number

Minimum number of words in a keyword.

Default value: 1

Allowed values: 1..4

maxWords optional Number

Maximum number of words in a keyword.

Default value: 1

Allowed values: 1..4

HTTP/1.1 200 OK
{
  "type": "success",
  "handler": "success_audiences",
  "value": [
    {
      "name": String,
      "weight": Number,
      "perc": Float,
      "type": String
    },
    ...
  ]
}

Audiences Insights | User top words and mentions

post
/audiences/user/topwords
{
  "user_id": "123",
  "social": "twitter"
}

Header

Field Type Description
Authorization String

Users token

Parameter

Field Type Description
user_id Number

User ID

social String

Social

Allowed values: twitter, instagram, facebook, webdata

limit optional Number

Limit number of results.

Default value: 50

minWords optional Number

Minimum number of words in a keyword.

Default value: 1

Allowed values: 1..4

maxWords optional Number

Maximum number of words in a keyword.

Default value: 1

Allowed values: 1..4

HTTP/1.1 200 OK
{
  "type": "success",
  "handler": "success_audiences",
  "value": [
    {
      "name": String,
      "weight": Number,
      "perc": Float,
      "type": String
    },
    ...
  ]
}

Connector

Connector | Get export csv params

post
/research/:id/csv
{
 filter_id: '123',
 filters: {},
 name: 'test'
}

Header

Field Type Description
Authorization String

Users token.

Parameter

Field Type Description
filters optional Array

Filters array of Object.

include_comments optional Boolean

If include comments.

HTTP/1.1 200 OK
{
  "type": "success",
  "handler": "success_resource_found",
  "value": {
     "params": Object,
     "queueName": String,
     "jobName": String,
     "job": Object,
   }
}

CustomML

CustomML | Add dataset to custom ml

post
/custom_ml/add_dataset
{
  "name": "My Dataset",
  "label_ids":["ID1", "ID2"]
}

Header

Field Type Description
Authorization String

Users token.

Parameter

Field Type Description
name String

Dataset name.

label_ids Object

The labels ids.

HTTP/1.1 200 OK
{
  "type": "success",
  "handler": "success_add_dataset"
}

CustomML | Stop an active deploy

post
/custom_ml/deploy/:deployId/stop

Header

Field Type Description
Authorization String

Users token.

Parameter

Field Type Description
name String

Dataset name.

label_ids Object

The labels ids.

HTTP/1.1 200 OK
{
  "type": "success",
  "handler": "success_add_dataset"
}

CustomML | Delete imported research

post
/custom_ml/remove_imported_research
{
  "datasourceId": "123",
}

Header

Field Type Description
Authorization String

Users token.

Parameter

Field Type Description
datasourceId String

Datasource ID.

HTTP/1.1 200 OK
{
  "type": "success",
  "handler": "success_remove_imported_datasource"
}

CustomML | Get datasource

post
/custom_ml/get_datasource/:id
{
  "id": "123",
}

Header

Field Type Description
Authorization String

Users token.

Parameter

Field Type Description
id String

Datasource ID.

HTTP/1.1 200 OK
{
  "type": "success",
  "handler": "success_get_datasource",
  "value": {}
}

CustomML | List datasources

post
/custom_ml/list_datasource
{
  "id": "123",
}

Header

Field Type Description
Authorization String

Users token.

HTTP/1.1 200 OK
{
  "type": "success",
  "handler": "success_get_datasource",
  "value": {}
}

CustomML | Import Csv

post
/custom_ml/import_csv

Header

Field Type Description
Authorization String

Users token.

Content-Type String

text/csv

Parameter

Field Type Description
fsier File

File Csv to upload

name String

name of the datasource

HTTP/1.1 200 OK
{
  "type": "success",
  "handler": "success_research_import_started"
}

CustomML | Import research

post
/custom_ml/import_research
{
  "name":"pippo"
  "id": "123",
  "filters": {
     "id": filter_id,
     "topic_id": topic_id
   }
}

Header

Field Type Description
Authorization String

Users token.

Parameter

Field Type Description
id String

Research ID.

filters optional Object

The filters' data.

HTTP/1.1 200 OK
{
  "type": "success",
  "handler": "success_research_import_started"
}

CustomML | Stop importing research

post
/custom_ml/stop_import
{
  "dataSourceId": "123",
  "topic_id": 567
}

Header

Field Type Description
Authorization String

Users token.

Parameter

Field Type Description
id String

Research ID.

HTTP/1.1 200 OK
{
  "type": "success",
  "handler": "success_import_stopped"
}

Custom Dashboards

Custom Dashboards | Add custom dashboard

post
/dashboards
{
  "config": "..",
  "dashboard_name": "My new dashboard name"
}

Header

Field Type Description
Authorization String

Users token.

Parameter

Field Type Description
dashboard_name String

Custom dashboard name.

config String

Config in json stringify.

env String

Dashboard type.

Allowed values: audience, analytics

research String

'Shared' or research/audience id.

HTTP/1.1 200 OK
{
  "type": "success",
  "handler": "success_dashboard_add"
}

Custom Dashboards | Delete custom dashboard

delete
/dashboards/:id
{
  "id": "..",
}

Header

Field Type Description
Authorization String

Users token.

Parameter

Field Type Description
id String

Custom dashboard id.

HTTP/1.1 200 OK
{
  "type": "success",
  "handler": "success_dashboard_delete"
}

Custom Dashboards | Get available insights for user

get
/dashboards/users/insights

Header

Field Type Description
Authorization String

Users token.

HTTP/1.1 200 OK
{
  "type": "success",
  "handler": "success_dashboard_insights",
  "value": [String]
}

Custom Dashboards | Get user dashboard

get
/dashboards/:id

Header

Field Type Description
Authorization String

Users token.

Parameter

Field Type Description
id String

Custom dashboard id.

HTTP/1.1 200 OK
{
  "type": "success",
  "handler": "success_dashboard_list",
  "value": {
    "id": String, 
    "username": String,
    "dashboard_name": String,
    "config": String
   }
}

Custom Dashboards | Get user dashboards

get
/dashboards

Header

Field Type Description
Authorization String

Users token.

Parameter

Field Type Description
env optional String

In querystring to return dashboards based on env.

Allowed values: audience, analytics

HTTP/1.1 200 OK
{
  "type": "success",
  "handler": "success_dashboard_list",
  "value": [
    {
      "id": String, 
      "username": String,
      "dashboard_name": String,
      "config": String,
      "env": String
    },
    ...
  ]
}

Custom Dashboards | Update dashboard

put
/dashboards
{
  "id": "123",
  "dashboard_name": "My new dashboard name"
}

Header

Field Type Description
Authorization String

Users token.

Parameter

Field Type Description
dashboard_name String

Custom dashboard name.

config optional String

Config in json stringify.

env String

Dashboard type.

Allowed values: audience, analytics

research String

'Shared' or research/audience id.

HTTP/1.1 200 OK
{
  "type": "success",
  "handler": "success_dashboard_updated"
}

Facebook @deprecated

Facebook @deprecated | Get pages liked by a page

post
/topic/facebook/liked
{
  "item_id": "15087023444"
}

Header

Field Type Description
Authorization String

Users token.

Parameter

Field Type Description
item_id String

Facebook Page ID

HTTP/1.1 200 OK
{
  "type": "success",
  "handler": "success_fb_liked",
  "value": [
    {
      "name": String,
      "id": String,
      "profile_picture": String,
      "link": String,
      "about": String,
      "category": String,
      "type": String,
      "engagement": {
        "count": Number,
        "social_sentence": String
      },
      "verification_status": String,
      "location": {
        "city": String,
        "country": String,
        "state": String,
        "street": String,
        "zip": String
      },
      "talking_about_count": Number
    },
    ...
  ]
}

GEOTAG

GEOTAG | Toggle GEOTAG

post
/research/:id/geotag/enable
{
  "topic_id": "123",
  "enable": true
}

Header

Field Type Description
Authorization String

Users token.

Path parameters

Field Type Description
id String

Research ID.

Parameter

Field Type Description
enable Boolean

Enabled status.

 HTTP/1.1 200 OK
{
  "type": "success",
  "handler": "success_geotag_updated",
  "value": {
    "geotag": true
  }
}

Global Web Index

Global Web Index | Get GWI data

post
/audiences/:list_id/gwi/question/:questionId

Header

Field Type Description
Authorization String

Users token.

Parameter

Field Type Description
question String

to ask to GWI.

Allowed values: question

audience String

's id to enrich with GWI data.

Allowed values: :audience

HTTP/1.1 200 OK
{
  "type": "success",
  "handler": "success_gwi_info",
  "value": [...]
}

Global Web Index | Get GWI info by ID

get
/gwi/:info/id/:id

Header

Field Type Description
Authorization String

Users token.

Parameter

Field Type Description
info String

GWI info.

Allowed values: audience, question, option, location

id String

GWI info ID.

HTTP/1.1 200 OK
{
  "type": "success",
  "handler": "success_gwi_info",
  "value": {
    "id": String,
    "name": String,
    ...
  }
}

Global Web Index | Get GWI info by ID

get
/gwi/questions

Header

Field Type Description
Authorization String

Users token.

HTTP/1.1 200 OK
{
  "type": "success",
  "handler": "success_gwi_info",
  "value": [{id, name}]
}

Global Web Index | Get GWI info by name

get
/gwi/:info/name/:name/:contains

Header

Field Type Description
Authorization String

Users token.

Parameter

Field Type Description
info String

GWI info.

Allowed values: audience, question, option, location

name String

GWI info name.

contains optional String

Toggle contains search for name.

Default value: false

Allowed values: true, false

HTTP/1.1 200 OK
{
  "type": "success",
  "handler": "success_gwi_info",
  "value": [...]
}

Global Web Index | Get GWI mean

post
/gwi/mean/:question

Header

Field Type Description
Authorization String

Users token.

Parameter

Field Type Description
question String

Question ID.

HTTP/1.1 200 OK
{
  "type": "success",
  "handler": "success_gwi_stats",
  "value": {
    ...
  }
}

Global Web Index | Get GWI stats

post
/gwi/q

Header

Field Type Description
Authorization String

Users token.

Parameter

Field Type Description
question String

Question ID.

audiences Array

Audiences IDs.

options optional Array

Options IDs.

filter optional Object

Filter object { audiences: [...], locations: [...], waves: [...] }.

HTTP/1.1 200 OK
{
  "type": "success",
  "handler": "success_gwi_stats",
  "value": {
    ...
  }
}

NEW Research

NEW Research | Delete research

delete
/research/:id

Header

Field Type Description
Authorization String

Users token.

Path parameters

Field Type Description
id String

Topic ID.

HTTP/1.1 200 OK
{
  "type": "success",
  "handler": "success_delete_topic"
}

NEW Research | Get research

get
/research/:id

Header

Field Type Description
Authorization String

Users token.

Path parameters

Field Type Description
id String

Topic ID.

HTTP/1.1 200 OK
{
  "type": "success",
  "handler": "success_topic_get",
  "value": {
    "id": String, 
    "ai": Object, 
    "backlog_done": Timestamp, 
    "backlog_end": Timestamp, 
    "backlog_start": Timestamp, 
    "created_at": Timestamp, 
    "description": String, 
    "queries": Array, 
    "progress": Number, 
    "sandbox": Boolean, 
    "schedule": Object, 
    "social": String, 
    "start_date": Timestamp, 
    "stop_date": Timestamp, 
    "threshold": Number, 
    "topic_name": String, 
    "queries": Array,
    "topic_status": String, 
    "username": String,
    "sources": Array,
    "buffering": Boolean
  }
}

NEW Research | Stop research

post
/research/:id/stop

Header

Field Type Description
Authorization String

Users token.

Parameter

Field Type Description
id String

Topic ID.

HTTP/1.1 200 OK
{
  "type": "success",
  "handler": "success_topic_stopped",
  "value": {
    "job": "123"
  }
}

Polygons

Polygons | Get Affinity

get
/audiences/polygons/get_affinity/:audience_id
{
  "audience_id": "1234",
}

Header

Field Type Description
Authorization String

Users token

HTTP/1.1 200 OK
{
  "type": "success",
  "handler": "success_audiences",
  "value": [
             { "audience_id": 1234,
               "audience_name": "Audience name"
               "polygons": {
                            "pairs": [ ... ],
                            "transformed_audiences": [ ... ]
                           }
             }
           ]

Polygons | List Affinity

get
/audiences/polygons/list_affinity

Header

Field Type Description
Authorization String

Users token

HTTP/1.1 200 OK
{
  "type": "success",
  "handler": "success_audiences",
  "value": [
             { "audience_id": 1234,
               "audience_name": "Audience name"
             }
           ]

Polygons | Polygons

post
/audiences/polygons
{
  "audiences": ["123", "124", "125"],
}

Header

Field Type Description
Authorization String

Users token

Parameter

Field Type Description
audiences String[]

List of audiences ID.

demographic boolean

True to enable age and gender analysis.

HTTP/1.1 200 OK
{
  "type": "success",
  "handler": "success_audiences",
          "value": {
    "pairs": [
      {
       "distance": 1.512513347095137e-16,
       "id1": "00",
       "id2": "11",
       "rank": 100
       },
      ...
    ],
    "transformed_audiences": [
      {
       "audience_id": "id_1",
       "polygon": {
         "x": [ 0.98576, 0.6328746, ...],
         "y": [ 0.43847, 0.4898745, ...]
        },
       "users": [
         {
          "id": "id",
          "inlier": 1,
          "point": [ 0.476380, 0.23675 ],
         },
         ...
        ]
      },
      ...
    ]
  }
}

Polygons | Polygons

get
/audiences/polygons/valid/:list_id

Header

Field Type Description
Authorization String

Users token

HTTP/1.1 200 OK
{
  "type": "success",
  "handler": "success_audiences",
  "value": {
    "list_id": 123
    "enriched": 1289
  }
}

Utility

Utility | Calculate square area

Get 4 equidistant points from a latitude, a longitude and a radius

post
/squarearea
{
  "lat": 41.9,
  "lng": 12.5,
  "radius": 10000
}

Header

Field Type Description
Authorization String

Users token.

Parameter

Field Type Description
lat Float

Latitude coordinate.

lng Float

Longitude coordinate.

radius Number

Radius in metres.

HTTP/1.1 200 OK
{
  "type": "success",
  "handler": "success_squarearea",
  "value": {
    "points": {
      "ne": {
         "lat": Number,
         "lng": Number
      },
      "se": {
         "lat": Number,
         "lng": Number
      },
      "sw": {
         "lat": Number,
         "lng": Number
      },
      "nw": {
         "lat": Number,
         "lng": Number
      }
   }
}

Utility | Get social user ID

Get social user ID of a username

get
/socialuser/userid/:social/:username
{
  "social": "twitter",
  "username": "google"
}

Header

Field Type Description
Authorization String

Users token.

Path parameters

Field Type Description
social String

Social.

Allowed values: twitter, instagram

username String

Username. Example: "google".

HTTP/1.1 200 OK
{
  "type": "success",
  "handler": "success_socialuser",
  "value": String
}

Generated with apidoc 1.2.0 - Mon Sep 23 2024 14:28:30 GMT+0000 (Coordinated Universal Time)