ObserversApi Resource

GET /observers

For an authenticated user, this method returns an ObserverList object which contains a list of observers that match the requirements specified explicitly/implicitly by the user

Request Parameters
name type description default constraints multivalued
detail query Specifies the amount of details retrieved by the method. Possible values: MAX, MIN. MAX means that the observers returned have the highest level of details possible, including all terms used as observer definitions. MIN means that a minimal level of details are included in the output, e.g., the name of the observer, its id, and language. Calls using MAX may take significantly longer to return than those using MIN. MIN "MAX" or "MIN" no
language query Specifies the language that the observer must be configured to (optional)   "AA" or "AB" or "AE" or "AF" or "AK" or "AM" or "AN" or "AR" or "AS" or "AV" or "AY" or "AZ" or "BA" or "BE" or "BG" or "BH" or "BI" or "BM" or "BN" or "BO" or "BR" or "BS" or "CA" or "CE" or "CH" or "CO" or "CR" or "CS" or "CU" or "CV" or "CY" or "DA" or "DE" or "DV" or "DZ" or "EE" or "EL" or "EN" or "EO" or "ES" or "ET" or "EU" or "FA" or "FF" or "FI" or "FJ" or "FO" or "FR" or "FY" or "GA" or "GD" or "GL" or "GN" or "GU" or "GV" or "HA" or "HE" or "HI" or "HO" or "HR" or "HT" or "HU" or "HY" or "HZ" or "IA" or "ID" or "IE" or "IG" or "II" or "IK" or "IO" or "IS" or "IT" or "IU" or "JA" or "JV" or "KA" or "KG" or "KI" or "KJ" or "KK" or "KL" or "KM" or "KN" or "KO" or "KR" or "KS" or "KU" or "KV" or "KW" or "KY" or "LA" or "LB" or "LG" or "LI" or "LN" or "LO" or "LT" or "LU" or "LV" or "MG" or "MH" or "MI" or "MK" or "ML" or "MN" or "MR" or "MS" or "MT" or "MY" or "NA" or "NB" or "ND" or "NE" or "NG" or "NL" or "NN" or "NO" or "NR" or "NV" or "NY" or "OC" or "OJ" or "OM" or "OR" or "OS" or "PA" or "PI" or "PL" or "PS" or "PT" or "QU" or "RM" or "RN" or "RO" or "RU" or "RW" or "SA" or "SC" or "SD" or "SE" or "SG" or "SI" or "SK" or "SL" or "SM" or "SN" or "SO" or "SQ" or "SR" or "SS" or "ST" or "SU" or "SV" or "SW" or "TA" or "TE" or "TG" or "TH" or "TI" or "TK" or "TL" or "TN" or "TO" or "TR" or "TS" or "TT" or "TW" or "TY" or "UG" or "UK" or "UNASSIGNED" or "UNHANDLED" or "UR" or "UZ" or "VE" or "VI" or "VO" or "WA" or "WO" or "XH" or "YI" or "YO" or "ZA" or "ZH" or "ZH_CN" or "ZH_TW" or "ZU" no
owner query Specifies whether the observers returned should be all that he has access to, or only those of which he is owner. Comma separated list of possible values: ALL, ME, SHARED, PUBLIC.     no
sectorId query If this parameter is specified, it specifies which sector the observer belongs to(optional)   required no
terms query The terms that the observer must subscribe to (optional)   max size: 10, min size: 0 yes
Response Body
media type data type description
application/json ObserverDetailsList (JSON) An json object containing the list of observers

Example

Request
GET /observers
Content-Type: */*
Accept: application/json

                
...
Response
HTTP/1.1 200 OK
Content-Type: application/json

                
{
  "observers" : [ {
    "description" : "...",
    "targetTerms" : [ "...", "..." ],
    "language" : "DA",
    "editable" : true,
    "disambiguationIncludeTerms" : [ "...", "..." ],
    "disambiguationExcludeTerms" : [ "...", "..." ],
    "id" : 12345,
    "name" : "...",
    "created" : { },
    "kpiId" : 12345
  }, {
    "description" : "...",
    "targetTerms" : [ "...", "..." ],
    "language" : "SG",
    "editable" : true,
    "disambiguationIncludeTerms" : [ "...", "..." ],
    "disambiguationExcludeTerms" : [ "...", "..." ],
    "id" : 12345,
    "name" : "...",
    "created" : { },
    "kpiId" : 12345
  } ]
}

POST /observers

This method allows the user to create a new customerObserver and Target.

The Content-Type in the header must be set to: application/json;charset="UTF-8" 

 https://ethersource.gavagai.se/ethersource/rest/v2/observers

Request Body
media type data type description
application/json Observer (JSON) The request parameter to create the observer. The contents of which is to be passed as a post parameter. It includes the following:

description: The description of the target that is to be setup

language: The language of the CustomerObserver as well as the template to use

name: The name to be specified for the CustomerObserver, Target Monitor and Target that are created

targetTerms: The terms to be included as TargetParts

disambiguateIncludeTerms: A list of words where at least one has to be within two sentences from the target terms for the document to be included. For instance, if we want to track Apple the company, we might want to guarantee that any of the words ['company', 'AAPL', 'mac'] is in its context.

disambiguateExcludeTerms: A list of words which cannot be within two sentences from the target terms for the document to be included. For instance, Apple shouldn't have any of the words ['fruit', 'banana', 'eat', 'pie'] within a two-sentence context.

Response Body
media type data type description
application/json Observer (JSON) A json object representing an customerObserver just created. It contains the name, the id and the date created.

Example

Request
POST /observers
Content-Type: application/json
Accept: application/json

                
{
  "targetTerms" : [ "...", "..." ],
  "language" : "LG",
  "name" : "...",
  "description" : "...",
  "disambiguationIncludeTerms" : [ "...", "..." ],
  "disambiguationExcludeTerms" : [ "...", "..." ]
}
Response
HTTP/1.1 201 Created
Content-Type: application/json

                
{
  "id" : 12345,
  "name" : "...",
  "created" : { },
  "kpiId" : 12345
}

GET /observers/mentions

For an authenticated user, this method returns the total mentions for all observers owned by the user in the specified time range(Please note, the timestamps are rounded to the nearest hours)

Request Parameters
name type description default constraints
includeTimestampValues query This parameter specifies whether the individual timestamp values are required false boolean
resolution query This parameter specifies resolution of the chunks to retrieve values for (HOUR, DAY, MONTH)   required
timestampBegin query This parameter specifies the beginning of the timerange   required
timestampEnd query This parameter specifies the end of the timerange   required
Response Body
media type data type description
application/json ObserversMentionsList (JSON) A json containing the observer and a totalmentions for the specified timerange.

Example

Request
GET /observers/mentions
Content-Type: */*
Accept: application/json

                
...
Response
HTTP/1.1 200 OK
Content-Type: application/json

                
{
  "totalNumberOfObservers" : 12345,
  "observersMentions" : [ {
    "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
  } ]
}

DELETE /observers/{id}

For an authenticated user, this method deletes a previously created observer, as long as the observer was created by the user.

Request Parameters
name type description default constraints
id path The id of observer for which the user wants to remove.   required, min: 1
sectorId query The id of the sector in the context of which the observer is requested to be removed. A negative value indicates that this parameter is not activated. If the sector is provided (indicated by a positive id), valid, owned by the calling user, the following may take place:
    • The observer is removed if it is referenced only by the sector indicated by sectorId.
      The reference between the observer and the sector indicated by sectorId is removed if the observer is referenced by a bookmark or any other sector.
    		• -1 int
    Response Body
    media type data type description
    application/json boolean (JSON) A boolean representing whether the operation was successful

    Example

    Request
    DELETE /observers/{id}
Content-Type: */*
Accept: application/json

                
...
    Response
    HTTP/1.1 204 No Content
Content-Type: application/json

                
...

    GET /observers/{id}

    For an authenticated user, this method returns all the details of a specified observer

    Request Parameters
    name type description constraints
    id path id of the observer required, min: 1
    Response Body
    media type data type description
    application/json ObserverDetails (JSON) An json object representing the observer

    Example

    Request
    GET /observers/{id}
Content-Type: */*
Accept: application/json

                
...
    Response
    HTTP/1.1 200 OK
Content-Type: application/json

                
{
  "description" : "...",
  "targetTerms" : [ "...", "..." ],
  "language" : "CY",
  "editable" : true,
  "disambiguationIncludeTerms" : [ "...", "..." ],
  "disambiguationExcludeTerms" : [ "...", "..." ],
  "id" : 12345,
  "name" : "...",
  "created" : { },
  "kpiId" : 12345
}

    PUT /observers/{id}

    This method allows the user to modify an observer that the user created previously. The language of the observer cannot be modified

    The Content-Type in the header must be set to: application/json;charset="UTF-8"

    Request Parameters
    name type description constraints
    id path The id of the observer to be modified required
    Request Body
    media type data type description
    application/json Observer (JSON) The request parameter to create the observer. The contents of which is to be passed as a post parameter. It includes the following:

    description: The description of the target that is to be setup

    language: The language of the CustomerObserver as well as the template to use

    name: The name to be specified for the CustomerObserver, Target Monitor and Target that are created

    targetTerms: The terms to be included as TargetParts

    Response Body
    media type data type description
    application/json Observer (JSON) A json object representing an customerObserver modified. It contains the name, the id and the date created.

    Example

    Request
    PUT /observers/{id}
Content-Type: application/json
Accept: application/json

                
{
  "targetTerms" : [ "...", "..." ],
  "language" : "IU",
  "name" : "...",
  "description" : "...",
  "disambiguationIncludeTerms" : [ "...", "..." ],
  "disambiguationExcludeTerms" : [ "...", "..." ]
}
    Response
    HTTP/1.1 204 No Content
Content-Type: application/json

                
{
  "id" : 12345,
  "name" : "...",
  "created" : { },
  "kpiId" : 12345
}

    GET /observers/{id}/associations

    Get associations, both trending and stable, for an observer.

    Request Parameters
    name type description default constraints
    id path The id of the observer   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 TrendingAndStableAssociations (JSON) A TrendingAndStableAssociations object containing both a list of trending associations and a list of stable associations as well as info about the observer

    Example

    Request
    GET /observers/{id}/associations
Content-Type: */*
Accept: application/json

                
...
    Response
    HTTP/1.1 200 OK
Content-Type: application/json

                
{
  "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 /observers/{id}/bookmark

    For an authenticated user, this method allows the user to remove a bookmarked observer from his bookmarks. If the provided bookmark is the only reference to the observer, then this method will remove both the bookmark and the bookmarked observer. However, if the bookmarked observer is also referenced by any sectors, then only the bookmark itself is removed.

    Request Parameters
    name type description constraints
    id path The id of the observer that the user wants to remove from his bookmarks. min: 1

    Example

    Request
    DELETE /observers/{id}/bookmark
Content-Type: */*

                
...
    Response
    HTTP/1.1 204 No Content

    POST /observers/{id}/bookmark

    For an authenticated user, this method allows to bookmark a observer for the user to view later. The condition is that the observer 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 observer that the user wants to bookmark min: 1
    Response Body
    media type data type description
    application/json ObserverBookmark (JSON) A json representing the bookmarked observer

    Example

    Request
    POST /observers/{id}/bookmark
Content-Type: */*
Accept: application/json

                
...
    Response
    HTTP/1.1 201 Created
Content-Type: application/json

                
{
  "observer" : {
    "id" : 12345,
    "name" : "...",
    "created" : { },
    "kpiId" : 12345
  },
  "user" : {
    "username" : "...",
    "firstName" : "...",
    "email" : "..."
  },
  "editable" : true,
  "language" : "EL"
}

    GET /observers/{id}/documentsdetails

    For an authenticated user, this method returns the documents which contribute to the frequency value or aggregate value for an observer 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/observers/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 observer for which the user requires documents   required
    aggregateId query Within the observer, the aggregate that the user is interested in. If aggregate id is not set, the return structure has values 1 for polarizationScore and 0 for poleId 0 int
    domain query Optional parameter, if specified, documentsdetails from this domain are returned    
    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 The id of the kpi matching the observer for which the user requires documents. Please note that this is only applicable if your observers have a parent-child relation. If not, specify the id of the observer that already subscribes to the kpi   required
    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)   "DAY" or "HOUR" or "MONTH"
    timestamp query The timestamp for which the user would like the documents    
    Response Body
    media type data type description
    application/json DocumentsDetails (JSON) A json containing the documents for the observer.

    Example

    Request
    GET /observers/{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 /observers/{id}/documentsdomains

    For an authenticated user, this method returns the domains which contribute to the total frequency value or aggregate value for an observer 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 the total frequency from the domain 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/observers/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 observer for which the user requires domains   required, min: 1
    aggregateId query Within the observer, the aggregate that the user is interested in. If aggregate id is not set, the return structure has values 1 for polarizationScore and 0 for poleId 0 int
    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 domain with zero value for polarizationScore in the results (not applicable of aggregateId = 0) false boolean
    kpiId query The id of the kpi matching the observer for which the user requires documents. Please note that this is only applicable if your observers have a parent-child relation. If not, specify the id of the observer that already subscribes to the kpi   required
    pageSize query Used for paging, the size of each page 10 int
    resolution query The resolution for which the user would like domain (HOUR, DAY, MONTH)   required
    timestamp query The timestamp for which the user would like the domain   required
    Response Body
    media type data type description
    application/json DocumentsDomains (JSON) A json containing the domain for the observer.

    Example

    Request
    GET /observers/{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 /observers/{id}/export

    For an authenticated user, export observer documents or stories to an Explorer https://explorer.gavagai.se) project

    Request Parameters
    name type description default constraints
    id path The id of the observer that the user wants 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 /observers/{id}/export
Content-Type: */*

                
...
    Response
    HTTP/1.1 201 Created

    GET /observers/{id}/mentions

    For an authenticated user, this method return the mentions of the specified observer 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 resolution, and each of these chunks get a mentions value Additionally, the user can enter a KPIid as a parameter, and will receive mentions for the observer in the context of the kpi

    Request Parameters
    name type description constraints
    id path The id of sector for which the user requires the mentions required
    kpiId query the id of kpi for which the wants observer mentions in the context of (optional). Please note that this is only applicable if your observers have a parent-child relation. If not, specify the id of the observer that already subscribes to the kpi required
    resolution query This parameter specifies resolution of the chunks to retrieve values for (HOUR, DAY, MONTH) required
    timestampBegin query This parameter specifies the beginning of the timerange required
    timestampEnd query This parameter specifies the end of the timerange required
    Response Body
    media type data type description
    application/json ObserverMentions (JSON) A json containing the observer and a timeseries of the mentions.

    Example

    Request
    GET /observers/{id}/mentions
Content-Type: */*
Accept: application/json

                
...
    Response
    HTTP/1.1 200 OK
Content-Type: application/json

                
{
  "observer" : {
    "id" : 12345,
    "name" : "...",
    "created" : { },
    "kpiId" : 12345
  },
  "mentions" : [ {
    "value" : 12345.0,
    "timestamp" : { },
    "quote" : "..."
  }, {
    "value" : 12345.0,
    "timestamp" : { },
    "quote" : "..."
  } ],
  "totalMentions" : 12345
}

    POST /observers/{id}/requestcopy

    For an authenticated user, this method allows to copy a observer

    Request Parameters
    name type description constraints
    id path The id of the observer 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 CopyObserverRequest (JSON) A json object representing an copy observer request. It contains the name, the id and the date created.

    Example

    Request
    POST /observers/{id}/requestcopy
Content-Type: */*
Accept: application/json

                
...
    Response
    HTTP/1.1 201 Created
Content-Type: application/json

                
{
  "observer" : {
    "id" : 12345,
    "name" : "...",
    "created" : { },
    "kpiId" : 12345
  },
  "id" : 12345,
  "sender" : {
    "username" : "...",
    "firstName" : "...",
    "email" : "..."
  },
  "recipient" : {
    "username" : "...",
    "firstName" : "...",
    "email" : "..."
  },
  "created" : { }
}

    GET /observers/{id}/sentiments

    For an authenticated user, this method returns the sentiment values for the observer, for each of the aggregates that are configured for the observer in the specified time range (if the user is allowed access to the observer)). 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 polarization 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/observers/1/
 sentiment? apiKey=123ok&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 observer for which the user requires the polarization values   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 ObserverSentiments (JSON) A json containing polarization values for the observer

    Example

    Request
    GET /observers/{id}/sentiments
Content-Type: */*
Accept: application/json

                
...
    Response
    HTTP/1.1 200 OK
Content-Type: application/json

                
{
  "curves" : [ {
    "aggregateId" : 12345,
    "name" : "...",
    "label" : "VIOLENCE"
  }, {
    "aggregateId" : 12345,
    "name" : "...",
    "label" : "VIOLENCE"
  } ],
  "sentimentValues" : [ {
    "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" : "..."
    } ]
  } ],
  "observer" : {
    "id" : 12345,
    "name" : "...",
    "created" : { },
    "kpiId" : 12345
  }
}

    GET /observers/{id}/stories

    For an authenticated user, this method returns all stories for the specified observer for the specified resolution based on the timestamp parameter. Please note: Valid resolutions are DAY and MONTH. The timestamps are rounded off to the nearest resolution; ie, DAY to 0 hour,MONTH to 1st day of the month. 

     https://ethersource.gavagai.se/ethersource/rest/v2/observers/1/
 stories?apiKey=123ok&timestamp=2013-10-08+00:
 00:00+CET&resolution=DAY

    Request Parameters
    name type description default constraints
    id path The id of observer which the user requires the stories   required, min: 1
    resolution query This parameter specifies resolution of the stories to retrieve (DAY, MONTH) DAY "DAY" or "HOUR" or "MONTH"
    showTones query false boolean
    timestamp query This parameter specifies the beginning of the timerange   required
    toneType query This parameter specifies which tone version of the stories response that will be returned (FREQUENCY (default), POSITIVITY, NEGATIVITY) FREQUENCY "FREQUENCY" or "NEGATIVITY" or "POSITIVITY"
    Response Body
    media type data type description
    application/json StoriesResponse (JSON) Json containing the available stories for the observer

    Example

    Request
    GET /observers/{id}/stories
Content-Type: */*
Accept: application/json

                
...
    Response
    HTTP/1.1 200 OK
Content-Type: application/json

                
{
  "observerId" : 12345,
  "startDate" : { },
  "endDate" : { },
  "stories" : [ {
    "headline" : { },
    "summary" : [ "...", "..." ],
    "documents" : [ {
      "title" : "...",
      "date" : { },
      "type" : { },
      "uri" : "..."
    }, {
      "title" : "...",
      "date" : { },
      "type" : { },
      "uri" : "..."
    } ],
    "tonalities" : { }
  }, {
    "headline" : { },
    "summary" : [ "...", "..." ],
    "documents" : [ {
      "title" : "...",
      "date" : { },
      "type" : { },
      "uri" : "..."
    }, {
      "title" : "...",
      "date" : { },
      "type" : { },
      "uri" : "..."
    } ],
    "tonalities" : { }
  } ]
}

    GET /observers/{id}/kpis/associations

    For an authenticated user, this method returns an observers all kpi associations between timestampBegin and timestampEnd

    Request Parameters
    name type description default constraints
    id path The id of observer   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 associations.

    Example

    Request
    GET /observers/{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 /observers/{id}/kpis/sentiments

    For an authenticated user, this method returns all kpi sentiments for the specified observer 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/observers/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§orId=2

    Request Parameters
    name type description default constraints
    id path The id of observer which the user requires the observers kpis sentiments   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"
    sectorId query The id of sector for which the user requires the observers kpis sentiments   required
    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 ObserverKpiSentiments (JSON) A json containing the available kpis in a sector and polarization values for each kpi in the sector.

    Example

    Request
    GET /observers/{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" : "DISSEMINATION"
  }, {
    "aggregateId" : 12345,
    "name" : "...",
    "label" : "COMPLIANCE"
  } ],
  "totalNumberOfKpis" : 12345
}

    GET /observers/{id}/associations/{association}/documentsdetails

    For an authenticated user, this method returns the documents which contribute to the associations for an observer at any given timestamp and resolution. The time range is specified using the timestamp, resolution and windowSize 

     https://ethersource.gavagai.se/ethersource/rest/v2/observer/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
    association path The association string for which the observer requires documents   required, max size: 2147483647, min size: 1
    id path The id of observer for which the user requires documents   required, min: 1
    domain query Optional parameter, if specified, documentsdetails from this domain are returned    
    firstResult query Used for paging, the first document the page starts with 0 int
    kpiId query The id of the kpi matching the observer for which the user requires documents. Please note that this is only applicable if your observers have a parent-child relation. If not, specify the id of the observer that already subscribes to the kpi   required
    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
    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 observer and association.

    Example

    Request
    GET /observers/{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 /observers/{id}/associations/{association}/documentsdomains

    For an authenticated user, this method returns the top domains for the documents which contribute to the associations for an observer at any given timestamp and resolution. The time range is specified using the timestamp, resolution and windowSize 

     https://ethersource.gavagai.se/ethersource/rest/v2/observer/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
    association path The association string for which the observer requires domains   required
    id path The id of observer for which the user requires domains   required, min: 1
    firstResult query Used for paging, the first document the page starts with 0 min: 0
    kpiId query The id of the kpi matching the observer for which the user requires domains. Please note that this is only applicable if your observers have a parent-child relation. If not, specify the id of the observer that already subscribes to the kpi   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 documents (HOUR, DAY, MONTH)   required
    timestamp query The timestamp 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 DocumentsDomains (JSON) A json containing the documents for the observer and association.

    Example

    Request
    GET /observers/{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 /observers/{id}/kpis/{kpiId}/connect

    For an authenticated user, this method allows the user to connect a previously created kpi to an observer owned by the user. The customer observer is modified such that the only the documents matching the condition specified in the kpi will match the resulting observer

    Request Parameters
    name type description constraints
    id path The id of observer which the user wishes to modify required, min: 1
    kpiId path The id of the kpi the user wants to add to the observer 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 /observers/{id}/kpis/{kpiId}/connect
Content-Type: */*
Accept: application/json

                
...
    Response
    HTTP/1.1 201 Created
Content-Type: application/json

                
...

    GET /observers/{id}/kpis/{kpiId}/stories

    For an authenticated user, this method returns all stories for the specified kpi related to the specified observer for the specified resolution based on the timestamp parameter. Please note: Valid resolutions are DAY and MONTH. The timestamps are rounded off to the nearest resolution; ie, DAY to 0 hour,MONTH to 1st day of the month. 

     https://ethersource.gavagai.se/ethersource/rest/v2/observers/1/kpis/12/
 stories?apiKey=123ok&timestamp=2013-10-08+00:00:00+CET&resolution=DAY

    Request Parameters
    name type description default constraints
    id path The id of observer which the user requires the stories   required, min: 1
    kpiId path The id of the kpi the user wants stories for   required, min: 1
    resolution query This parameter specifies resolution of the stories to retrieve (DAY, MONTH) DAY "DAY" or "HOUR" or "MONTH"
    showTones query false boolean
    timestamp query This parameter specifies the beginning of the time range ( format: yyyy-MM-dd HH:mm:ss z )   required
    toneType query This parameter specifies which tone version of the stories response that will be returned (FREQUENCY (default), POSITIVITY, NEGATIVITY) FREQUENCY "FREQUENCY" or "NEGATIVITY" or "POSITIVITY"
    Response Body
    media type data type description
    application/json StoriesResponse (JSON) A json containing the available stories for the kpi

    Example

    Request
    GET /observers/{id}/kpis/{kpiId}/stories
Content-Type: */*
Accept: application/json

                
...
    Response
    HTTP/1.1 200 OK
Content-Type: application/json

                
{
  "observerId" : 12345,
  "startDate" : { },
  "endDate" : { },
  "stories" : [ {
    "headline" : { },
    "summary" : [ "...", "..." ],
    "documents" : [ {
      "title" : "...",
      "date" : { },
      "type" : { },
      "uri" : "..."
    }, {
      "title" : "...",
      "date" : { },
      "type" : { },
      "uri" : "..."
    } ],
    "tonalities" : { }
  }, {
    "headline" : { },
    "summary" : [ "...", "..." ],
    "documents" : [ {
      "title" : "...",
      "date" : { },
      "type" : { },
      "uri" : "..."
    }, {
      "title" : "...",
      "date" : { },
      "type" : { },
      "uri" : "..."
    } ],
    "tonalities" : { }
  } ]
}