Brand24 – API Documentation

Document version: 1.7

Last change: 10-02-2016

Brand24 – API Documentation ................................................................................................................ 1

GENERAL .............................................................................................................................................. 1
Introduction ..................................................................................................................................... 1
API Domain ...................................................................................................................................... 1
Basic definitions............................................................................................................................... 1
Terms of use .................................................................................................................................... 2
Security ............................................................................................................................................ 2
Errors description ............................................................................................................................ 2
Suggested implementation of downloading mentions ................................................................... 2
API ACTIONS ........................................................................................................................................ 2
MENTIONS DOWNLOAD – downloading mentions to your database ........................................... 2
LIST OF PROJECTS – preview list of account’s projects ................................................................... 4
PROJECT’S CONFIGURATION – preview configuration of project ................................................... 5
PROJECT CREATE - create new project ........................................................................................... 5
PROJECT EDIT – edit existing project’s configuration ..................................................................... 6
PROJECT DELETE – delete existing project ...................................................................................... 7
PROJECT MENTIONS COUNTS - getting the number of mentions in a certain period ................... 8

GENERAL
Introduction
API Brand24 was created to let Brand24 customers download to their database mentions found by
Brand24

API returns results in XML format

API Domain
All API actions are available on following domains:

 English version: https://api.brand24.net

 Polish version: https://api.brand24.pl
 Indonesian version: https://api.brand24.co.id

Basic definitions
 Account – set of projects. Each account has unique ID and secret access key
  Project - set of mentions found in the process of monitoring the keywords which are defined
in project
 Keyword - phrase monitored by Brand24 in the Internet. Each keyword may also include
additional words – required and excluded

Terms of use
API Brand24 was created to let Brand24 customers download to their database mentions found by
Brand24. API was not created to expose mentions directly from Brand24 to all kinds of client’s
widgets (e.g. Flash controls), mobile devices etc.

You should use API Brand24 only to download mentions from Brand24 to your database. If you
want to pass mentions to your clients, widgets, mobile devices etc you should pass mentions from
your database.

Security
To access API it is required to pass in action’s parameters access key. Access key is attached to the
account and is available in Brand24 customer service.

Errors description
If an error occurs during executing API action, XML will be returned in the following form:

<error code="ERROR NUMBER ">ERROR DESCRIPTION </error>

Each action may return different kinds of error codes, however there are some global codes, which
can appear during processing any action:

 code=”1” – unidentified Brand24-side error

 code=”2” – resource which client requests does not exist (e.g. the project with a specified ID
does not exist)
 code=”3” – security error, incorrect value of access key parameter

Suggested implementation of downloading mentions

See DOWNLOADING MENTIONS action’s description

API ACTIONS

MENTIONS DOWNLOAD – downloading mentions to your database

Description
It is basic and most important action. Use this action to download mentions from Brand24 to your
database.

Actions returns mentions found by Brand24 for a chosen project. Mentions are ordered by
mention’s ID asceding (from the latest to the newest).

Suggested implementation of downloading mentions:

 1. Execute /api/results-download/ action
2. Save mentions from returned XML to your database.
3. Save <id> of latest mention from returned XML. You will use this value in “rid” param in later
requests.
4. If in returned XML “more” attribute equals 1 (<results more="1”), it means that in Brand24
database there are more mentions. You should request action “/api/results-download/”
again with “rid” with latest mention id you saved in step number 3.
5. Repeat steps 1-4 until “more”=”0” (<results more="0”)

Repeat steps 1-5 every time you want to download new mentions. The whole process shouldn’t be
executed more frequent that every 15 minutes.

URI

/api/results-
download/?key=ACCESS_KEY&sid=PROJECT_ID&rid=ID_RESULT&count=MAX_RESULTS&created_dat
e_from=RESULT_MIN_CREATED_DATE &sentiment=SENTIMENT

Parameters:
 sid – project’s id
 rid (optional)– mentions with ID greater than “rid” will be returned. You should pass here
the highest mention’s id of choosen project you already have in your database. See Steps 1-5
above to understand better the conecpt
 count (optional) – the maximum number of results which will be returned. Default 500.
Maximum 1000
 created_date_from – the minimum result created date – required date format YYYY-MM-DD
(2015-02-01).
 sentiment (optional) – it filters results by the sentiment. Possible values:
o empty (default) – all
o 1 – only positive
o 2 – only negative

Response format

<?xml version="1.0" encoding="UTF-8" ?>

<results more="1 – there are more mentions in Brand24 to download, 0 – there are no more
mentions to download" returned="HOW MANY RESULTS DID THE XML RETURN">
<result>
<id>mention’s ID in Brand24(string)</id>
<url>Website or entry address</url>
<title>Website or entry title</title>
<contet>A part of a page, which includes searched word or the whole
mention</content>
<sentiment> 0 - neutral, 1 - positive, 2 - negative</sentiment>
<created_date> Date of webpage or mentions publication (If the system is not able to
detect the date, it inserts a date of founding the entry)</created_date>
<category>Mention categories as a number:
 1 - Microblogs
2 - Blogs
3 - Forums
4 - News
5 - Other
6 - Video
7 - Photos
8 - Facebook
</category>
<!—below tags appear only if the mentions contains author’s -->
<author>Author’s name </author>
<author_url>Author’s URL </author>
<gender>Author’s gender
m – male
f – female
u - unknown/undefined
Element is visible only if author’s gender info option is active in Brand24
version (brand24.pl, brand24.net or brand24.co.id). Actually author’s
gender info option is active only on brand24.pl version.
</gender>
<valuable>result’s valuable
-1 - spam or low value result
1 – normal
2 - result from trusted host
</valuable>
<estimated_social_reach>
Estimated Social Reach – visible only if that value exists and account has
access to it.
</estimated_social_reach>
</result>
</results>

LIST OF PROJECTS – preview list of account’s projects

Description
It returns the list of account’s projects ordered by project’s ID asceding

URI
/api/projects/?aid=ACCOUNTS_ID&key=ACCESS_KEY

Parameters
 aid – account’s id, given by Brand24 client service
 phrases – if 1, it will also show a set of monitored phrases for each project

Response format
<projects>
<project>
<id>PROJECT’S ID</id>
<name>PROJECT’S NAME</name>
<queries>
<query>… //description of a tag „query”, see in a description of a
method/api/project-info
 </project>
<project>….</project>
<project>....</project>
</projects>

PROJECT’S CONFIGURATION – preview configuration of project

Description
It returns a list of monitored keywords in a specified project. There is also given a list of required and
excluded words (if specified in project configuration). Every keyword appears as an individual tag
<query>, which can include tags <and> and <or>, which may contain required word (in tag
<contains>) or excluded word (in tag <not_contains>). There is also added attribute id to every
keyword – value necessary in project edition.

URI
/api/project-info/?sid=PROJECT_ID&key=ACCESS_KEY

Parameter
 sid - id of a project defined in brand24

Response format
<project>
<id>PROJECT_ID </id>
<queries>
<query keywword="MONITORED_KEYWORD" id=”KEYWORD_ID”>
<and>
<contains>REQUIRED WORD </contains>
<not_contains>EXCLUDED WORD </not_contains>
</and>
</query>
<query keyword=”SECOND_MONITORED_KEYWORD” id=”SECOND_KEYWORD_ID”>
<!—this keyword does not include any required or excluded word, so it has no tag <and> and
<or> -->
</query>
<query>….</query> <!—next monitored keyword -->
</queries>
</project>

PROJECT CREATE - create new project

Description
It creates a new project to a certain account

URI
/api/project-add/
Parameter
Parameters should be sent with POST method.

 aid – defined in brand24 account’s id

 key – API_KEY

 name – project’s name

 phrases_relevant - monitored keywords in a set of words (tabular variable) e.g.:

phrases_relevant [ 0 ] = keyword 1
phrases_relevant [ 1 ] = keyword 2
…
phrases_relevant [ N ] = keyword N

 phrases_required - required words in a set of words (tabular variable) e.g.:

phrases_required [ 0 ] = required word(s) for the keyword 1

phrases_required [ 1 ] = required word(s) for the keyword 2
…
phrases_required [ N ] = required word(s) for the keyword N

Each position MUST refer to the table phrases_relevant and phrases_required. If you want to
attach many required words to a keyword, you should separate them with comas.

 phrases_excluded - excluded words in a set of words (tabular variable) e.g.:

phrases_excluded [ 0 ] = excluded word(s) for the keyword 1

phrases_excluded [ 1 ] = excluded word(s) for the keyword 2
…
phrases_excluded [ N ] = excluded word(s) for the keyword N

Each position MUST refer to the table phrases_relevant and phrases_excluded. If you want to
attach many excluded words to a keyword, you should separate them with comas.

Response format
<result>PROJECT_ID</result>

PROJECT EDIT – edit existing project’s configuration

Description
It edits specified project (saves/correct project’s value – name, keywords, required and excluded
words). Cognately to the first step of a new project edition in a dashboard.
URI
/api/project-edit/

Parameters
Parameters should be sent by a POST method.
 sid - id of a project defined in brand24

 aid – – defined in brand24 account’s id

 key – API_KEY

 name – project’s name

 phrases_relevant - keywords in a set of words (tabular variable) e.g.:

phrases_relevant [ WORD_1_ID ] = word 1

phrases_relevant [ WORD_2_ID] = word 2
…
phrases_relevant [ WORD_N_ID] = word N

 phrases_required - required words in a set of words (tabular variable) e.g.:

phrases_required [WORD_1_ID] = required word(s) for the keyword 1

phrases_required [WORD_2_ID] = required word(s) for the keyword 2
…
phrases_required [WORD_N_ID] = required word(s) for the keyword N'

Each position MUST refer to the table phrases_relevant and phrases_required. If you want to
attach many required words to a keyword, you should separate them with comas.

 phrases_excluded - excluded words in a set of words (tabular variable) e.g.:

phrases_excluded [WORD_1_ID] = excluded word(s) for the keyword 1

phrases_excluded [WORD_2_ID]= excluded word(s) for the keyword 2'
…
phrases_excluded [WORD_N_ID] = excluded word(s) for the keyword N'

Each position MUST refer to the table phrases_relevant and phrases_excluded. If you want to
attach many excluded words to a keyword, you should separate them with comas.

Response format
<result>PROJECT_ID</result>

PROJECT DELETE – delete existing project

Description
It deletes specified project, which belongs to a certain account.
URI
/api/project-delete/?sid=PROJECT_ID&aid=ACCOUNTS_ID&key= ACCESS_KEY

Parameters
 sid - id of a project defined in brand24

 aid – defined in brand24 account’s id

Response format
<result>1</result>

PROJECT MENTIONS COUNTS - getting the number of mentions in a certain period

Description
It brings out the number of mentions in a certain period for a certain project with a sentiment and
category division. The number of mentions may be given as a sum for the whole period or with a
division for days.

URI
/api/results-count/?key=ACCESS_KEY &sid=PROJECT_ID&d1=START_DAY&d2=END_DAY&group=

Parameters
 sid - id of a project defined in brand24

 d1 – start day in YYYY-MM-DD format

 d2 – end day in YYYY-MM-DD format

 group(optional) –if ”day” there are also numbers for particular days

Response format

When the results are combined:

<results>
<id>PROJECT_ID</id>
<date1>BEGINNING_DATE_OF_A_PERIOD_WHICH_REFERS_TO_A_REPORT</date1>
<date2> CLOSING_DATE_OF_A_PERIOD_WHICH_REFERS_TO_A_REPORT </daate2>
<count>NUMBER_OF_ALL_ENTRIES </count>
<positive>NUMBER_OF_POSITIVE ENTRIES</pisitive>
<negative> NUMBER_OF_NEGATIVE ENTRIES </negative>
<neutral> NUMBER_OF_NEUTRAL ENTRIES </neutral>
<categories>
<category>
<id>CATEGORY_ID </id>
<name>CATEGORY_NAME</name>
<count>NUMBER_OF_MENTIONS_IN_A_CATEGORY</count>
<positive> NUMBER_OF_POSITIVE_MENTIONS_IN_A_CATEGORY </pisitive>
<negative> NUMBER_OF_NEGATIVE_MENTIONS_IN_A_CATEGORY </negative>
<neutral> NUMBER_OF_NEUTRAL_MENTIONS_IN_A_CATEGORY </neutral>
 </category>
<category>
<id>SECOND_CATEGORY_ID</id>
<name> SECOND_CATEGORY_NAME</name>
<count>NUMBER_OF_MENTIONS_IN_A_SECOND_CATEGORY</count>
<positive> NUMBER_OF_POSITIVE_MENTIONS_IN_A_SECOND_CATEGORY </pisitive>
<negative>
NUMBER_OF_NEGATIVE_MENTIONS_IN_A_SECOND_CATEGORY</negative>
<neutral> NUMBER_OF_NEUTRAL_MENTIONS_IN_A_SECOND_CATEGORY </neutral>
</category>
</categories>
</results>

When the results are grouped in days (parameter group = day):

<results>
<id>PROJECT_ID</id>
<date1>BEGINNING_DATE_OF_A_PERIOD_WHICH_REFERS_TO_A_REPORT</date1>
<date2> CLOSING_DATE_OF_A_PERIOD_WHICH_REFERS_TO_A_REPORT </daate2>
<result>
<day> DAY_WHICH_THE_RESULTS_REFER_TO</day>
<count>NUMBER_OF_ALL_ENTRIES </count>
<positive>NUMBER_OF_POSITIVE ENTRIES</pisitive>
<negative> NUMBER_OF_NEGATIVE ENTRIES </negative>
<neutral> NUMBER_OF_NEUTRAL ENTRIES </neutral>
<categories>
<category>
<id>CATEGORY_ID </id>
<name>CATEGORY_NAME</name>
<count>NUMBER_OF_MENTIONS_IN_A_CATEGORY</count>
<positive> NUMBER_OF_POSITIVE_MENTIONS_IN_A_CATEGORY </pisitive>
<negative> NUMBER_OF_NEGATIVE_MENTIONS_IN_A_CATEGORY </negative>
<neutral> NUMBER_OF_NEUTRAL_MENTIONS_IN_A_CATEGORY </neutral>
</category>
<category>
<id>SECOND_CATEGORY_ID</id>
<name> SECOND_CATEGORY_NAME</name>
<count>NUMBER_OF_MENTIONS_IN_A_SECOND_CATEGORY</count>
<positive> NUMBER_OF_POSITIVE_MENTIONS_IN_A_SECOND_CATEGORY </pisitive>
<negative>
NUMBER_OF_NEGATIVE_MENTIONS_IN_A_SECOND_CATEGORY</negative>
<neutral> NUMBER_OF_NEUTRAL_MENTIONS_IN_A_SECOND_CATEGORY </neutral>
</category>
</categories>
</result>
<result>
<day> SECOND_DAY_WHICH_THE_RESULTS_REFER_TO</day>
<count>NUMBER_OF_ALL_ENTRIES </count>
<positive>NUMBER_OF_POSITIVE ENTRIES</pisitive>
<negative> NUMBER_OF_NEGATIVE ENTRIES </negative>
 <neutral> NUMBER_OF_NEUTRAL ENTRIES </neutral>
<categories>
<category>
<id>CATEGORY_ID </id>
<name>CATEGORY_NAME</name>
<count>NUMBER_OF_MENTIONS_IN_A_CATEGORY</count>
<positive> NUMBER_OF_POSITIVE_MENTIONS_IN_A_CATEGORY </pisitive>
<negative> NUMBER_OF_NEGATIVE_MENTIONS_IN_A_CATEGORY </negative>
<neutral> NUMBER_OF_NEUTRAL_MENTIONS_IN_A_CATEGORY </neutral>
</category>
<category>
<id>SECOND_CATEGORY_ID</id>
<name> SECOND_CATEGORY_NAME</name>
<count>NUMBER_OF_MENTIONS_IN_A_SECOND_CATEGORY</count>
<positive> NUMBER_OF_POSITIVE_MENTIONS_IN_A_SECOND_CATEGORY </pisitive>
<negative>
NUMBER_OF_NEGATIVE_MENTIONS_IN_A_SECOND_CATEGORY</negative>
<neutral> NUMBER_OF_NEUTRAL_MENTIONS_IN_A_SECOND_CATEGORY </neutral>
</category>
</categories>
</result>
</results>