- Home
- Resources
- SectorsApi
GET /sectors
For an authenticated user, this method returns all the visible Sectors the user is allowed to
see,
https://ethersource.gavagai.se/ethersource/rest/v2/
sectors?apiKey=123ok&firstResult=0&pageSize=10
Request Parameters
name |
type |
description |
default |
constraints |
accessType |
query |
The parameter selects if we want to see only the sectors which have accessType set
to public, or all sectors, public as well as private. Possible values (ALL,
PUBLIC, SUBSCRIBABLE), default is set to ALL. |
ALL |
"ALL" or "PRIVATE" or "PUBLIC" or "SUBSCRIBABLE" |
firstResult |
query |
The index of the first result, starts with 0 |
|
required |
pageSize |
query |
The number of sectors in each page. If you want the first 5 sectors you specify
firstResult=0 and pageSize=5. Next firstResult=5 and pageSize=5 will give you the
next 5 etc. |
|
required |
Response Body
media type |
data type |
description |
application/json |
SectorsResponse
(JSON) |
A json containing the available sectors and the total amount of sectors. |
Example
Request
GET /sectors
Content-Type: */*
Accept: application/json
...
Response
HTTP/1.1 200 OK
Content-Type: application/json
{
"sectors" : [ {
"id" : 12345,
"title" : "...",
"language" : "LG",
"tariff" : { }
}, {
"id" : 12345,
"title" : "...",
"language" : "YI",
"tariff" : { }
} ],
"totalNumberOfSectors" : 12345
}
POST /sectors
For an authenticated user, this method create a new sector given a title and a language. The
access type of the newly created sector will be set to private.
The Content-Type in the header must be set to: application/json;charset="UTF-8"
https://ethersource.gavagai.se/ethersource/rest/v2/
sectors?apiKey=123
Request Body
media type |
data type |
description |
application/json |
Sector
(JSON) |
The sector to create. |
application/xml |
sector
(XML) |
Response Body
media type |
data type |
description |
application/json |
Sector
(JSON) |
The newly created sector. |
Example
Request
POST /sectors
Content-Type: application/json
Accept: application/json
{
"id" : 12345,
"title" : "...",
"language" : "GU",
"tariff" : { }
}
Response
HTTP/1.1 201 Created
Content-Type: application/json
{
"id" : 12345,
"title" : "...",
"language" : "RM",
"tariff" : { }
}
DELETE /sectors/{id}
For an authenticated user, this method deletes a previously created sector, as long as the
sector was created by the user, and is accessible only by the user (PRIVATE access)
Request Parameters
name |
type |
description |
default |
constraints |
id |
path |
The id of sector for which the user wants to remove |
|
required, min: 1 |
removeObservers |
query |
While removing the sector, specified whether all the associated observers owned by
the user must also be removed |
true |
boolean |
Response Body
media type |
data type |
description |
application/json |
boolean
(JSON) |
A boolean representing whether the operation was successful |
Example
Request
DELETE /sectors/{id}
Content-Type: */*
Accept: application/json
...
Response
HTTP/1.1 204 No Content
Content-Type: application/json
...
GET /sectors/{id}
For an authenticated user, this method returns information for a given sector.
https://ethersource.gavagai.se/ethersource/rest/v2/
sectors/id?apiKey=123ok&fields=title,description,language,kpis,observers
Request Parameters
name |
type |
description |
constraints |
id |
path |
The id of the sector for which to obtain information. |
required, min: 1 |
Response Body
media type |
data type |
description |
application/json |
SectorThin
(JSON) |
A json containing the requested information about the sector. |
Example
Request
GET /sectors/{id}
Content-Type: */*
Accept: application/json
...
Response
HTTP/1.1 200 OK
Content-Type: application/json
{
"id" : 12345,
"title" : "...",
"language" : "BE",
"observers" : [ {
"id" : 12345,
"name" : "...",
"created" : { },
"editable" : true
}, {
"id" : 12345,
"name" : "...",
"created" : { },
"editable" : true
} ],
"kpis" : [ {
"id" : 12345,
"name" : "...",
"editable" : true
}, {
"id" : 12345,
"name" : "...",
"editable" : true
} ],
"editable" : true
}
PUT /sectors/{id}
For an authenticated user, this method modify a previously created sector. The sector must be
created by the user and the language of the sector cannot be changed.
https://ethersource.gavagai.se/ethersource/rest/v2/
sectors?apiKey=123
Request Parameters
name |
type |
description |
constraints |
id |
path |
The id of the sector to be modified |
required |
Request Body
media type |
data type |
description |
application/json |
Sector
(JSON) |
The modified sector details. |
application/xml |
sector
(XML) |
Response Body
media type |
data type |
description |
application/json |
Sector
(JSON) |
The modified sector. |
Example
Request
PUT /sectors/{id}
Content-Type: application/json
Accept: application/json
{
"id" : 12345,
"title" : "...",
"language" : "DA",
"tariff" : { }
}
Response
HTTP/1.1 204 No Content
Content-Type: application/json
{
"id" : 12345,
"title" : "...",
"language" : "TR",
"tariff" : { }
}
GET /sectors/{id}/associations
Get trending associations and stable associations for a whole sector. For each observer in
the sector as well as for the aggregate of all observers for the sector you will get two
lists of associations: one for trending associations and one for stable associations. You
also get the basic information about the corresponding observers
Request Parameters
name |
type |
description |
default |
constraints |
id |
path |
id for the sector |
|
required |
backlogDays |
query |
Number of days from which to calculate the background associations. Default is
180. |
180 |
int |
endDate |
query |
The end date for which to gather associations |
|
|
maxResults |
query |
The maximum number of associations you require. Default is 3. |
3 |
int |
startDate |
query |
The start date for which to gather associations |
|
|
Response Body
media type |
data type |
description |
application/json |
TrendingAndStableAssociationsList
(JSON) |
Wrapper object containing a list of TrendingAndStableAssociations objects, one for
each observer and one extra for the aggregated index |
Example
Request
GET /sectors/{id}/associations
Content-Type: */*
Accept: application/json
...
Response
HTTP/1.1 200 OK
Content-Type: application/json
{
"trendingAndStableAssociations" : [ {
"trendingAssociations" : [ {
"word" : "...",
"strength" : 12345.0,
"documentCount" : 12345,
"forWord" : "..."
}, {
"word" : "...",
"strength" : 12345.0,
"documentCount" : 12345,
"forWord" : "..."
} ],
"observer" : {
"id" : 12345,
"name" : "...",
"created" : { },
"kpiId" : 12345
},
"stableAssociations" : [ {
"strength" : 12345.0,
"word" : "..."
}, {
"strength" : 12345.0,
"word" : "..."
} ],
"timestamp" : { }
}, {
"trendingAssociations" : [ {
"word" : "...",
"strength" : 12345.0,
"documentCount" : 12345,
"forWord" : "..."
}, {
"word" : "...",
"strength" : 12345.0,
"documentCount" : 12345,
"forWord" : "..."
} ],
"observer" : {
"id" : 12345,
"name" : "...",
"created" : { },
"kpiId" : 12345
},
"stableAssociations" : [ {
"strength" : 12345.0,
"word" : "..."
}, {
"strength" : 12345.0,
"word" : "..."
} ],
"timestamp" : { }
} ]
}
DELETE /sectors/{id}/bookmark
For an authenticated user, this method allows the user to remove a bookmarked sector from
their bookmarks. Since the bookmark is the only reference to the sector, this method also
tries to remove the sector and the participating observers. However, if the authenticated
user does not have the right to remove the sector, it is left intact.
Request Parameters
name |
type |
description |
constraints |
id |
path |
The id of the sector that the user wants to remove from his bookmarks |
min: 1 |
Example
Request
DELETE /sectors/{id}/bookmark
Content-Type: */*
...
Response
HTTP/1.1 204 No Content
POST /sectors/{id}/bookmark
For an authenticated user, this method allows to bookmark a sector for the user to view
later. The condition is that the sector must be publicly visible or the user must own it and
the user should not already have a bookmark for it
Request Parameters
name |
type |
description |
constraints |
id |
path |
The id of the sector that the user wants to bookmark |
min: 1 |
Response Body
media type |
data type |
description |
application/json |
SectorBookmark
(JSON) |
A json representing the bookmarked sector |
Example
Request
POST /sectors/{id}/bookmark
Content-Type: */*
Accept: application/json
...
Response
HTTP/1.1 201 Created
Content-Type: application/json
{
"sector" : {
"id" : 12345,
"title" : "...",
"language" : "AS",
"tariff" : { }
},
"user" : {
"username" : "...",
"firstName" : "...",
"email" : "..."
},
"editable" : true
}
GET /sectors/{id}/documentsdetails
For an authenticated user, this method returns the documents which contribute to the
frequency value or aggregate value for a sector at any given timestamp and resolution.
The time range is specified using the timestamp and resolution
If aggregateId is not set, the documents which contribute to the frequency are returned
ordered by the date they were published in descending order. If the aggregateId is set, the
documents are ordered by the polarization value in descending order
https://ethersource.gavagai.se/ethersource/rest/v2/sectors/1/documentsdetails?
apiKey=123ok&aggregateId=1&kpiId=1×tamp=2013-10
-08+00:00:00+CEST&resolution=DAY
Request Parameters
name |
type |
description |
default |
constraints |
id |
path |
The id of sector for which the user requires the documents |
|
required, min: 1 |
aggregateId |
query |
Within the sector, the aggregate that the user is interested in. If aggregate id
is not set, the return structure has values 1 for polarizationScore and poleId |
0 |
min: 0 |
domain |
query |
Parameter to specify if documentdetails from a particular domain are required |
|
|
firstResult |
query |
Used for paging, the first document the page starts with |
0 |
int |
includeZeroValues |
query |
A boolean that can be used to specify if you would like to include documents with
zero value for polarizationScore in the results (not applicable of aggregateId =
0) |
false |
boolean |
kpiId |
query |
Within the sector, the id of the KPI the user is interested in |
0 |
min: 0 |
pageSize |
query |
Used for paging, the size of each page |
10 |
int |
resolution |
query |
The resolution for which the user would like documents (HOUR, DAY, MONTH) |
|
required |
timestamp |
query |
The timestamp for which the user would like the documents |
|
required |
Response Body
media type |
data type |
description |
application/json |
DocumentsDetails
(JSON) |
A json containing the documents for the sector. |
Example
Request
GET /sectors/{id}/documentsdetails
Content-Type: */*
Accept: application/json
...
Response
HTTP/1.1 200 OK
Content-Type: application/json
{
"documentDetailsRows" : [ {
"documentUri" : "...",
"documentTitle" : "...",
"polarizationScore" : 12345.0,
"date" : { },
"poleId" : 12345,
"mediaType" : "..."
}, {
"documentUri" : "...",
"documentTitle" : "...",
"polarizationScore" : 12345.0,
"date" : { },
"poleId" : 12345,
"mediaType" : "..."
} ],
"totalCount" : 12345
}
GET /sectors/{id}/documentsdomains
For an authenticated user, this method returns the top domains for documents which contribute
to the frequency value or aggregate value for a sector at any given timestamp and resolution.
The time range is specified using the timestamp and resolution
If aggregateId is not set, the domains which contribute to the frequency are returned ordered
by their URLs in descending order. If the aggregateId is set, the domains are ordered by the
total polarization value in descending order
https://ethersource.gavagai.se/ethersource/rest/v2/sectors/1/documentsdomains?
apiKey=123ok&aggregateId=1&kpiId=1×tamp=2013-10
-08+00:00:00+CEST&resolution=DAY
Request Parameters
name |
type |
description |
default |
constraints |
id |
path |
The id of sector for which the user requires the domains |
|
required, min: 1 |
aggregateId |
query |
Within the sector, the aggregate that the user is interested in. If aggregate id
is not set, the return structure has a value equal to the frequency for
polarizationValue and 0 for poleId |
0 |
min: 0 |
firstResult |
query |
Used for paging, the first domain the page starts with |
0 |
int |
includeZeroValues |
query |
A boolean that can be used to specify if you would like to include domains with
zero value for sumpolarizationScore in the results (not applicable of aggregateId
= 0) |
false |
boolean |
kpiId |
query |
Within the sector, the id of the KPI the user is interested in |
0 |
min: 0 |
pageSize |
query |
Used for paging, the size of each page |
10 |
int |
resolution |
query |
The resolution for which the user would like domains (HOUR, DAY, MONTH) |
|
required |
timestamp |
query |
The timestamp for which the user would like the domains |
|
required |
Response Body
media type |
data type |
description |
application/json |
DocumentsDomains
(JSON) |
A json containing the domains for the sector. |
Example
Request
GET /sectors/{id}/documentsdomains
Content-Type: */*
Accept: application/json
...
Response
HTTP/1.1 200 OK
Content-Type: application/json
{
"documentDomainRows" : [ {
"documentDomain" : "...",
"poleId" : 12345,
"sumPolarizationScore" : 12345.0,
"freq" : 12345
}, {
"documentDomain" : "...",
"poleId" : 12345,
"sumPolarizationScore" : 12345.0,
"freq" : 12345
} ],
"totalCount" : 12345
}
POST /sectors/{id}/export
For an authenticated user, export Sector documents or stories to an Explorer https://explorer.gavagai.se) projects
Request Parameters
name |
type |
description |
default |
constraints |
id |
path |
The id of the Sector that the user want to export to explorer |
|
required, min: 1 |
dataType |
query |
This parameter specifies if the data exported will be based on the stories
generated or on the content of the urls (i.e the text of the webpage) |
DOCUMENT_CONTENT_DATA |
"DOCUMENT_CONTENT_DATA" or "STORIES_DATA" |
from |
query |
This parameter specifies the beginning of the time range ( format: yyyy-MM-dd
HH:mm:ss z ) |
|
required |
to |
query |
This parameter specifies the end of the time range (format: yyyy-MM-dd HH:mm:ss z) |
|
required |
Example
Request
POST /sectors/{id}/export
Content-Type: */*
...
Response
HTTP/1.1 201 Created
GET /sectors/{id}/kpis
The method will return all the visible (to the authenticated user) KPIs of a particular
sector.
Request Parameters
name |
type |
description |
constraints |
id |
path |
The id of the sector. |
required |
Response Body
media type |
data type |
description |
application/json |
SectorKPIs
(JSON) |
A json structure containing the KPIs of the sector.
If there is any problem during the execution of this method an error code and message
will be returned. The format of this error code will be similar to the following:
{"message":"wrong api key", "resultCode":"API_KEY_WRONG"}}
|
Example
Request
GET /sectors/{id}/kpis
Content-Type: */*
Accept: application/json
...
Response
HTTP/1.1 200 OK
Content-Type: application/json
{
"sector" : {
"id" : 12345,
"title" : "...",
"language" : "KA",
"tariff" : { }
},
"kpis" : [ {
"id" : 12345,
"name" : "...",
"editable" : true
}, {
"id" : 12345,
"name" : "...",
"editable" : true
} ]
}
GET /sectors/{id}/observers
For an authenticated user, this method returns all observers that the user is allowed to see
in a particular sector(specified by sector id)
https://ethersource.gavagai.se/ethersource/rest/v2/sectors/1/observers?
apiKey=123ok
Request Parameters
name |
type |
description |
constraints |
id |
path |
The id of sector for which the user requires the observers This parameter
specifies the end of the timerange |
required, min: 1 |
Response Body
media type |
data type |
description |
application/json |
ObserverList
(JSON) |
A json containing the available observers in the sector |
Example
Request
GET /sectors/{id}/observers
Content-Type: */*
Accept: application/json
...
Response
HTTP/1.1 200 OK
Content-Type: application/json
{
"observers" : [ {
"id" : 12345,
"name" : "...",
"created" : { },
"kpiId" : 12345
}, {
"id" : 12345,
"name" : "...",
"created" : { },
"kpiId" : 12345
} ]
}
POST /sectors/{id}/requestcopy
For an authenticated user, this method allows to copy a sector
Request Parameters
name |
type |
description |
constraints |
id |
path |
The id of the sector that the user wants to copy |
required, min: 1 |
userId |
query |
The userId of the user that will be the copy owner |
required |
Response Body
media type |
data type |
description |
application/json |
CopySectorRequest
(JSON) |
A json object representing an sector copy request. It contains the name, the id and
the date created. |
Example
Request
POST /sectors/{id}/requestcopy
Content-Type: */*
Accept: application/json
...
Response
HTTP/1.1 201 Created
Content-Type: application/json
{
"sector" : {
"id" : 12345,
"title" : "...",
"language" : "CR",
"tariff" : { }
},
"id" : 12345,
"sender" : {
"username" : "...",
"firstName" : "...",
"email" : "..."
},
"recipient" : {
"username" : "...",
"firstName" : "...",
"email" : "..."
},
"created" : { }
}
POST /sectors/{id}/subscribe
For an authenticated user, this method allows to subscribe to a sector
Request Parameters
name |
type |
description |
constraints |
id |
path |
The id of the sector that the user wants to subscribe to |
required, min: 1 |
Response Body
media type |
data type |
description |
application/json |
boolean
(JSON) |
A boolean representing whether the operation was successful |
Example
Request
POST /sectors/{id}/subscribe
Content-Type: */*
Accept: application/json
...
Response
HTTP/1.1 201 Created
Content-Type: application/json
...
POST /sectors/{id}/unsubscribe
For an authenticated user, this method allows to unsubscribe to a sector
Request Parameters
name |
type |
description |
constraints |
id |
path |
The id of the sector that the user wants to unsubscribe |
required, min: 1 |
Response Body
media type |
data type |
description |
application/json |
boolean
(JSON) |
A boolean representing whether the operation was successful |
Example
Request
POST /sectors/{id}/unsubscribe
Content-Type: */*
Accept: application/json
...
Response
HTTP/1.1 201 Created
Content-Type: application/json
...
GET /sectors/{sectorId}/annotations
Finds annotations in a sector between fromDate and toDate
Request Parameters
name |
type |
description |
default |
constraints |
sectorId |
path |
id of the sector |
|
required, min: 1 |
firstResult |
query |
|
0 |
int |
fromDate |
query |
|
|
|
pageSize |
query |
|
50 |
int |
toDate |
query |
|
|
|
Response Body
media type |
data type |
description |
application/json |
SectorAnnotations
(JSON) |
|
Example
Request
GET /sectors/{sectorId}/annotations
Content-Type: */*
Accept: application/json
...
Response
HTTP/1.1 200 OK
Content-Type: application/json
{
"annotations" : [ {
"id" : 12345,
"resolution" : "DAY",
"date" : { },
"created" : { },
"text" : "...",
"author" : {
"name" : "...",
"email" : "..."
},
"createdBy" : "...",
"observerIds" : [ 12345, 12345 ],
"kpiIds" : [ 12345, 12345 ]
}, {
"id" : 12345,
"resolution" : "DAY",
"date" : { },
"created" : { },
"text" : "...",
"author" : {
"name" : "...",
"email" : "..."
},
"createdBy" : "...",
"observerIds" : [ 12345, 12345 ],
"kpiIds" : [ 12345, 12345 ]
} ]
}
POST /sectors/{sectorId}/annotations
Creates an annotation in the sector
Request Parameters
name |
type |
description |
constraints |
sectorId |
path |
id of the sector |
required, min: 1 |
Request Body
media type |
data type |
application/json |
SectorAnnotationRequest
(JSON) |
application/xml |
sectorAnnotationRequest
(XML) |
Response Body
media type |
data type |
description |
application/json |
SectorAnnotation
(JSON) |
|
Example
Request
POST /sectors/{sectorId}/annotations
Content-Type: application/json
Accept: application/json
{
"resolution" : "HOUR",
"date" : { },
"text" : "...",
"author" : {
"name" : "...",
"email" : "..."
},
"observerIds" : [ 12345, 12345 ],
"kpiIds" : [ 12345, 12345 ]
}
Response
HTTP/1.1 201 Created
Content-Type: application/json
{
"id" : 12345,
"resolution" : "DAY",
"date" : { },
"created" : { },
"text" : "...",
"author" : {
"name" : "...",
"email" : "..."
},
"createdBy" : "...",
"observerIds" : [ 12345, 12345 ],
"kpiIds" : [ 12345, 12345 ]
}
GET /sectors/{id}/kpis/associations
For an authenticated user, this method returns a sector's all kpi associations between
timestampBegin and timestampEnd
Request Parameters
name |
type |
description |
default |
constraints |
id |
path |
The id of sector |
|
required |
maxResult |
query |
Controls how many trending and stable topics you get back |
10 |
int |
timestampBegin |
query |
The start of the period |
|
|
timestampEnd |
query |
The end of the period |
|
|
Response Body
media type |
data type |
description |
application/json |
KpisAssociationsResponse
(JSON) |
A json containing the documents for the sector. |
Example
Request
GET /sectors/{id}/kpis/associations
Content-Type: */*
Accept: application/json
...
Response
HTTP/1.1 200 OK
Content-Type: application/json
{
"kpiAssociations" : [ {
"kpi" : {
"id" : 12345,
"name" : "...",
"editable" : true
},
"stable" : [ {
"strength" : 12345.0,
"word" : "..."
}, {
"strength" : 12345.0,
"word" : "..."
} ],
"trending" : [ {
"word" : "...",
"strength" : 12345.0,
"documentCount" : 12345,
"forWord" : "..."
}, {
"word" : "...",
"strength" : 12345.0,
"documentCount" : 12345,
"forWord" : "..."
} ]
}, {
"kpi" : {
"id" : 12345,
"name" : "...",
"editable" : true
},
"stable" : [ {
"strength" : 12345.0,
"word" : "..."
}, {
"strength" : 12345.0,
"word" : "..."
} ],
"trending" : [ {
"word" : "...",
"strength" : 12345.0,
"documentCount" : 12345,
"forWord" : "..."
}, {
"word" : "...",
"strength" : 12345.0,
"documentCount" : 12345,
"forWord" : "..."
} ]
} ]
}
GET /sectors/{id}/kpis/mentions
For an authenticated user, this method returns all KPIs that the user is allowed to see in a
particular sector(specified by sector id) as well as the mentions/frequencies of those KPIs
in the specified time range.
The time range is specified using the timestampBegin and timestampEnd parameters, and this
time range is further divided into chunks of size (windowSize * resolution), and each of
these chunks get a frequency value
https://ethersource.gavagai.se/ethersource/rest/v2/sectors/1/kpi/mentions?
apiKey=123ok§orId=1×tampBegin=2013-10-08+00:
00:00+CEST×tampEnd=2013-10-10+00:00:00+CEST&windowSize=1&resolution=
DAY
Request Parameters
name |
type |
description |
constraints |
id |
path |
The id of sector for which the user requires the observers' details |
required |
resolution |
query |
This parameter specifies resolution of the chunks to retrieve values for (HOUR,
DAY, MONTH) |
"DAY" or "HOUR" or "MONTH" |
timestampBegin |
query |
This parameter specifies the beginning of the timerange |
|
timestampEnd |
query |
This parameter specifies the end of the timerange |
|
windowSize |
query |
This parameter specifies the number of 'resolutions' to include in a chunk.
Default value is 1. |
int |
Response Body
media type |
data type |
description |
application/json |
SectorKPIResponse
(JSON) |
A json containing the available sector and the total amount of sectors. |
Example
Request
GET /sectors/{id}/kpis/mentions
Content-Type: */*
Accept: application/json
...
Response
HTTP/1.1 200 OK
Content-Type: application/json
{
"sectorMentions" : {
"totalNumberOfKPIs" : 12345,
"kpiMentions" : [ {
"mentions" : [ { }, { } ],
"kpi" : { }
}, {
"mentions" : [ { }, { } ],
"kpi" : { }
} ],
"averageMentions" : [ {
"value" : 12345.0,
"timestamp" : { },
"quote" : "..."
}, {
"value" : 12345.0,
"timestamp" : { },
"quote" : "..."
} ]
},
"observerGroupMentions" : [ {
"observer" : {
"id" : 12345,
"name" : "...",
"created" : { },
"kpiId" : 12345
},
"kpiMentions" : [ {
"mentions" : [ { }, { } ],
"kpi" : { }
}, {
"mentions" : [ { }, { } ],
"kpi" : { }
} ]
}, {
"observer" : {
"id" : 12345,
"name" : "...",
"created" : { },
"kpiId" : 12345
},
"kpiMentions" : [ {
"mentions" : [ { }, { } ],
"kpi" : { }
}, {
"mentions" : [ { }, { } ],
"kpi" : { }
} ]
} ]
}
GET /sectors/{id}/kpis/sentiments
For an authenticated user, this method returns all kpi sentiments that the user is allowed to
see in a particular sector(specified by sector id)
The time range is specified using the timestampBegin and timestampEnd parameters, and this
time range is further divided into chunks of size resolution, and each of these chunks get a
mentions value
Please note: The timestamps that are returned are rounded off to the nearest resolution;ie,
HOUR is rounded off to 0 minutes, DAY to 0 hour, MONTH to 1st day of the month. Values are
returned in resolution chunks from this rounded off value
https://ethersource.gavagai.se/ethersource/rest/v2/sectors/1/kpis/
sentiment?apiKey=123ok§orId=1×tampBegin=2013-10-08+00:
00:00+CEST×tampEnd=2013-10-10+00:00:00+CEST&resolution=DAY
Request Parameters
name |
type |
description |
default |
constraints |
id |
path |
The id of sector for which the user requires the observers' details |
|
required |
includeQuotes |
query |
This parameter specifies whether the result should be populated with quotes or
not. The quotes will be visible on the frequency curve |
false |
boolean |
resolution |
query |
This parameter specifies resolution of the chunks to retrieve values for (HOUR,
DAY, MONTH) |
|
"DAY" or "HOUR" or "MONTH" |
timestampBegin |
query |
This parameter specifies the beginning of the timerange |
|
|
timestampEnd |
query |
This parameter specifies the end of the timerange |
|
|
Response Body
media type |
data type |
description |
application/json |
SectorKpiSentiments
(JSON) |
A json containing the available kpis in a sector and polarization values for each kpi
in the sector. |
Example
Request
GET /sectors/{id}/kpis/sentiments
Content-Type: */*
Accept: application/json
...
Response
HTTP/1.1 200 OK
Content-Type: application/json
{
"kpiSentimentValues" : [ {
"sentimentValues" : [ {
"aggregateId" : 12345,
"values" : [ { }, { } ]
}, {
"aggregateId" : 12345,
"values" : [ { }, { } ]
} ],
"kpi" : {
"id" : 12345,
"name" : "...",
"editable" : true
}
}, {
"sentimentValues" : [ {
"aggregateId" : 12345,
"values" : [ { }, { } ]
}, {
"aggregateId" : 12345,
"values" : [ { }, { } ]
} ],
"kpi" : {
"id" : 12345,
"name" : "...",
"editable" : true
}
} ],
"curves" : [ {
"aggregateId" : 12345,
"name" : "...",
"label" : "EFFICIENCY"
}, {
"aggregateId" : 12345,
"name" : "...",
"label" : "GOVERNANCE"
} ],
"totalNumberOfKpis" : 12345
}
GET /sectors/{id}/observers/mentions
For an authenticated user, this method returns all observers that the user is allowed to see
in a particular sector(specified by sector id) as well as the mentions of those observers in
the specified time range. It also returns the average number of mentions for all the
observers for each timestamp
The time range is specified using the timestampBegin and timestampEnd parameters, and this
time range is further divided into chunks of size resolution, and each of these chunks get a
mentions value
Please note: The timestamps that are returned are rounded off to the nearest resolution;ie,
HOUR is rounded off to 0 minutes, DAY to 0 hour, MONTH to 1st day of the month. Values are
returned in resolution chunks from this rounded off value
https://ethersource.gavagai.se/ethersource/rest/v2/sectors/1/observers/
mentions? apiKey=123ok§orId=1×tampBegin=2013-10-08+00:
00:00+CEST×tampEnd=2013-10-10+00:00:00+CEST&resolution= DAY
Request Parameters
name |
type |
description |
constraints |
id |
path |
The id of sector for which the user requires the observers' details |
required |
resolution |
query |
This parameter specifies resolution of the chunks to retrieve values for (HOUR,
DAY, MONTH) |
"DAY" or "HOUR" or "MONTH" |
timestampBegin |
query |
This parameter specifies the beginning of the timerange |
|
timestampEnd |
query |
This parameter specifies the end of the timerange |
|
Response Body
media type |
data type |
description |
application/json |
SectorObserversMentions
(JSON) |
A json containing the available sectors and the mentions for each observer in the
sector of sectors. |
Example
Request
GET /sectors/{id}/observers/mentions
Content-Type: */*
Accept: application/json
...
Response
HTTP/1.1 200 OK
Content-Type: application/json
{
"averageMentions" : [ {
"value" : 12345.0,
"timestamp" : { },
"quote" : "..."
}, {
"value" : 12345.0,
"timestamp" : { },
"quote" : "..."
} ],
"totalNumberOfObservers" : 12345,
"observerMentions" : [ {
"observer" : {
"id" : 12345,
"name" : "...",
"created" : { },
"kpiId" : 12345
},
"mentions" : [ {
"value" : 12345.0,
"timestamp" : { },
"quote" : "..."
}, {
"value" : 12345.0,
"timestamp" : { },
"quote" : "..."
} ],
"totalMentions" : 12345
}, {
"observer" : {
"id" : 12345,
"name" : "...",
"created" : { },
"kpiId" : 12345
},
"mentions" : [ {
"value" : 12345.0,
"timestamp" : { },
"quote" : "..."
}, {
"value" : 12345.0,
"timestamp" : { },
"quote" : "..."
} ],
"totalMentions" : 12345
} ]
}
GET /sectors/{id}/observers/sentiments
For an authenticated user, this method returns all observers that the user is allowed to see
in a particular sector(specified by sector id) as well as the sentiment values for each of
the aggregates that are configured for the sector, for each of those observers in the
specified time range. It also returns the average average polarization values for each
aggregate for all the observers for each timestamp
The time range is specified using the timestampBegin and timestampEnd parameters, and this
time range is further divided into chunks of size resolution, and each of these chunks get a
mentions value
Additionally, the user can enter a KPIid as a parameter, and will receive the polarization
values for the observers in context of the KPI
Please note: The timestamps that are returned are rounded off to the nearest resolution;ie,
HOUR is rounded off to 0 minutes, DAY to 0 hour, MONTH to 1st day of the month. Values are
returned in resolution chunks from this rounded off value
https://ethersource.gavagai.se/ethersource/rest/v2/sectors/1/observers/
sentiment? apiKey=123ok§orId=1×tampBegin=2013-10-08+00:
00:00+CEST×tampEnd=2013-10-10+00:00:00+CEST&resolution= DAY
Request Parameters
name |
type |
description |
default |
constraints |
id |
path |
The id of sector for which the user requires the observers' details |
|
required |
includeQuotes |
query |
This parameter specifies whether the result should be populated with quotes or
not. The quotes will be visible on the frequency curve |
false |
boolean |
kpiId |
query |
the id if the kpi the user would like values for (optional) |
0 |
int |
resolution |
query |
This parameter specifies resolution of the chunks to retrieve values for (HOUR,
DAY, MONTH) |
|
"DAY" or "HOUR" or "MONTH" |
timestampBegin |
query |
This parameter specifies the beginning of the timerange |
|
|
timestampEnd |
query |
This parameter specifies the end of the timerange |
|
|
Response Body
media type |
data type |
description |
application/json |
SectorSentiments
(JSON) |
A json containing the available observers in a sector and polarization values for
each observer in the sector. |
Example
Request
GET /sectors/{id}/observers/sentiments
Content-Type: */*
Accept: application/json
...
Response
HTTP/1.1 200 OK
Content-Type: application/json
{
"averageSentimentValues" : [ {
"aggregateId" : 12345,
"values" : [ {
"value" : 12345.0,
"timestamp" : { },
"quote" : "..."
}, {
"value" : 12345.0,
"timestamp" : { },
"quote" : "..."
} ]
}, {
"aggregateId" : 12345,
"values" : [ {
"value" : 12345.0,
"timestamp" : { },
"quote" : "..."
}, {
"value" : 12345.0,
"timestamp" : { },
"quote" : "..."
} ]
} ],
"observerSentimentValues" : [ {
"sentimentValues" : [ {
"aggregateId" : 12345,
"values" : [ { }, { } ]
}, {
"aggregateId" : 12345,
"values" : [ { }, { } ]
} ],
"observer" : {
"id" : 12345,
"name" : "...",
"created" : { },
"kpiId" : 12345
}
}, {
"sentimentValues" : [ {
"aggregateId" : 12345,
"values" : [ { }, { } ]
}, {
"aggregateId" : 12345,
"values" : [ { }, { } ]
} ],
"observer" : {
"id" : 12345,
"name" : "...",
"created" : { },
"kpiId" : 12345
}
} ],
"curves" : [ {
"aggregateId" : 12345,
"name" : "...",
"label" : "VIOLENCE"
}, {
"aggregateId" : 12345,
"name" : "...",
"label" : "FEAR"
} ],
"totalNumberOfObservers" : 12345
}
DELETE /sectors/{sectorId}/annotations/{annotationId}
Request Parameters
name |
type |
description |
constraints |
annotationId |
path |
|
required, min: 1 |
sectorId |
path |
id of the sector |
required, min: 1 |
Response Body
media type |
data type |
description |
application/json |
boolean
(JSON) |
|
Example
Request
DELETE /sectors/{sectorId}/annotations/{annotationId}
Content-Type: */*
Accept: application/json
...
Response
HTTP/1.1 204 No Content
Content-Type: application/json
...
PUT /sectors/{sectorId}/annotations/{annotationId}
Update an annotation
Request Parameters
name |
type |
description |
constraints |
annotationId |
path |
iud of the annotation |
required, min: 1 |
sectorId |
path |
id of the sector |
required, min: 1 |
Request Body
media type |
data type |
application/json |
SectorAnnotationRequest
(JSON) |
application/xml |
sectorAnnotationRequest
(XML) |
Response Body
media type |
data type |
description |
application/json |
SectorAnnotation
(JSON) |
|
Example
Request
PUT /sectors/{sectorId}/annotations/{annotationId}
Content-Type: application/json
Accept: application/json
{
"resolution" : "HOUR",
"date" : { },
"text" : "...",
"author" : {
"name" : "...",
"email" : "..."
},
"observerIds" : [ 12345, 12345 ],
"kpiIds" : [ 12345, 12345 ]
}
Response
HTTP/1.1 204 No Content
Content-Type: application/json
{
"id" : 12345,
"resolution" : "MONTH",
"date" : { },
"created" : { },
"text" : "...",
"author" : {
"name" : "...",
"email" : "..."
},
"createdBy" : "...",
"observerIds" : [ 12345, 12345 ],
"kpiIds" : [ 12345, 12345 ]
}
GET /sectors/{id}/associations/{association}/documentsdetails
For an authenticated user, this method returns the documents which contribute to the
associations for an sector at any given timestamp and resolution.
The time range is specified using the timestamp and resolution
https://ethersource.gavagai.se/ethersource/rest/v2/sectors/3/associations/obama/documentsdetails?
apiKey=123ok×tamp=2013-10-08+00:00:00+CEST&resolution=DAY&kpiId=5
Request Parameters
name |
type |
description |
default |
constraints |
association |
path |
|
|
required, max size: 2147483647, min size: 1 |
id |
path |
The id of sector for which the user requires documents |
|
required, min: 1 |
domain |
query |
Parameter to specify if documentdetails from a particular domain are required |
|
|
firstResult |
query |
Used for paging, the first document the page starts with |
0 |
int |
kpiId |
query |
The id of kpi for which the user requires documents |
|
required, min: 0 |
pageSize |
query |
Used for paging, the size of each page |
10 |
int |
resolution |
query |
The resolution for which the user would like documents (HOUR, DAY, MONTH) |
|
required |
timestamp |
query |
The start time for which the user would like the documents |
|
required |
windowSize |
query |
The time period is calculated as resolution * windowSize |
1 |
min: 1 |
Response Body
media type |
data type |
description |
application/json |
DocumentsDetails
(JSON) |
A json containing the documents for the sector. |
Example
Request
GET /sectors/{id}/associations/{association}/documentsdetails
Content-Type: */*
Accept: application/json
...
Response
HTTP/1.1 200 OK
Content-Type: application/json
{
"documentDetailsRows" : [ {
"documentUri" : "...",
"documentTitle" : "...",
"polarizationScore" : 12345.0,
"date" : { },
"poleId" : 12345,
"mediaType" : "..."
}, {
"documentUri" : "...",
"documentTitle" : "...",
"polarizationScore" : 12345.0,
"date" : { },
"poleId" : 12345,
"mediaType" : "..."
} ],
"totalCount" : 12345
}
GET /sectors/{id}/associations/{association}/documentsdomains
For an authenticated user, this method returns the top domains for the documents which
contribute to the associations for an sector at any given timestamp and resolution.
The time range is specified using the timestamp and resolution
https://ethersource.gavagai.se/ethersource/rest/v2/sectors/3/associations/obama/documentsdetails?
apiKey=123ok×tamp=2013-10-08+00:00:00+CEST&resolution=DAY&kpiId=5
Request Parameters
name |
type |
description |
default |
constraints |
association |
path |
|
|
required |
id |
path |
The id of sector for which the user requires documents |
|
required, min: 1 |
firstResult |
query |
Used for paging, the first domains the page starts with |
0 |
min: 0 |
kpiId |
query |
The id of kpi for which the user requires documents |
|
required, min: 0 |
pageSize |
query |
Used for paging, the size of each page |
10 |
min: 0 |
resolution |
query |
The resolution for which the user would like domains (HOUR, DAY, MONTH) |
|
required |
timestamp |
query |
The start time for which the user would like the domains |
|
required |
windowSize |
query |
The time period is calculated as resolution * windowSize |
1 |
min: 1 |
Response Body
media type |
data type |
description |
application/json |
DocumentsDomains
(JSON) |
A json containing the documents for the sector. |
Example
Request
GET /sectors/{id}/associations/{association}/documentsdomains
Content-Type: */*
Accept: application/json
...
Response
HTTP/1.1 200 OK
Content-Type: application/json
{
"documentDomainRows" : [ {
"documentDomain" : "...",
"poleId" : 12345,
"sumPolarizationScore" : 12345.0,
"freq" : 12345
}, {
"documentDomain" : "...",
"poleId" : 12345,
"sumPolarizationScore" : 12345.0,
"freq" : 12345
} ],
"totalCount" : 12345
}
POST /sectors/{id}/kpis/{kpiId}/connect
For an authenticated user, this method connects a given sector with a given kpi.
https://ethersource.gavagai.se/ethersource/rest/v2/sectors/{sectorId}/kpis/{kpiId}/connect
Request Parameters
name |
type |
description |
constraints |
id |
path |
The id of the sector. |
required |
kpiId |
path |
The id of the kpi. |
required |
Response Body
media type |
data type |
description |
application/json |
KPIReference
(JSON) |
A json structure containing information about the outcome of the connect request. |
Example
Request
POST /sectors/{id}/kpis/{kpiId}/connect
Content-Type: application/json;charset="UTF-8"
Accept: application/json
...
Response
HTTP/1.1 201 Created
Content-Type: application/json
{
"id" : 12345,
"owner" : {
"username" : "...",
"firstName" : "...",
"email" : "..."
},
"keyPerformanceIndex" : {
"id" : 12345,
"name" : "...",
"editable" : true
},
"group" : {
"id" : 12345,
"name" : "..."
}
}
POST /sectors/{id}/observers/{observerId}/connect
For an authenticated user, this method connects an existing observer to a sector
Request Parameters
name |
type |
description |
constraints |
id |
path |
The id of sector |
required |
observerId |
path |
The id of the observer |
required |
Response Body
media type |
data type |
description |
application/json |
boolean
(JSON) |
A json structure containing information about the outcome of the connect request. |
Example
Request
POST /sectors/{id}/observers/{observerId}/connect
Content-Type: */*
Accept: application/json
...
Response
HTTP/1.1 201 Created
Content-Type: application/json
...