SectorsApi Resource

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&timestamp=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&timestamp=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&timestampBegin=2013-10-08+00:
 00:00+CEST&timestampEnd=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&timestampBegin=2013-10-08+00:
 00:00+CEST&timestampEnd=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&timestampBegin=2013-10-08+00:
 00:00+CEST&timestampEnd=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&timestampBegin=2013-10-08+00:
 00:00+CEST&timestampEnd=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&timestamp=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&timestamp=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

                
...