ExternalApiV2 Resource

A restful API to external methods of Ethersource. Returned data is encoded as json objects. The default endpoint to use is https://ethersource.gavagai.se/ethersource/rest/v2/. So to use getValue you should use https://ethersource.gavagai.se/ethersource/rest/v2/getValue For most of these externalApi methods, you need to have a list of your customerObserverViews. To get these, use the method listAllCustomerObserverViews

The API requires HTTP Basic Authentication, thus you need a username and a password to access the API. You will get this from a Gavagai operator.

Most API methods also require you to pass in an API key. You will get this as well from a Gavagai operator.

Version history:

v8 added several TopicTracker Methods to the api, only applicable to a TopicTrackerUser.

v7 added getValues(to get the Polarization Values for a CustomerObserver over a given Range), getMostRecentValues(to get the recent Polarization Values), getComparisonValues(to get the most recent values for a set of customerObserverViews, to compare them) to the api.

v6 added findAssociations to the api

v5 added findDocumentURIs to the api

v4 getTriggerMarker changed its matching algorithm slightly: now it matches a triggermarker within the given day or hour (or whatever resolution is set) regardless of the values of the smaller time fields, and not, as previously, the closest triggerMarker.

v3 trigger marker methods now reference a sensorSubscriptionId instead of a sensorId

v2 changed path in example call

v1 first version of api with getValue

Changes to Ethersource Api:

We have upgraded our api from Version 1 to Version 2. These are the changes that go along with this upgrade:

End Point: https://ethersource.gavagai.se/ethersource/rest/v2/
Documentation: https://ethersource.gavagai.se/ethersource/v2/apis/

1) For all the method calls, the outer wrapper that was returned with the JSON has been removed
2) The names of the fields as returned by the json have been modified
3) Values that were null, before were not output. They will now be output, with a NULL value
4) Arrays that had only one element, before we output as a single object. If the array was empty, the field was skipped. Now, irrespective of whether the array is empty/single object/multiple objects, the arrays are output as arrays
5) Before, Float values without a decimal value were output as Ints, they will now be output as floats with a ‘.0’
6)The order of the fields within the JSON have been changed
7) Method getValuesMultiple now takes a minimum of 2 customerObserverViewIds as a parameter. If 1 customerObserverViewId only is passed, an error is thrown

POST /createTargetMonitorAndCustomerObserver

For the topic tracker admin, this method allows the user to create a new customerObserver and Target for any user that the admin specifies. The customerObserver,targetMonitor and Target have the name specified.

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

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

Request Body
media type data type description
application/json CreateCustomerObserverRequest (JSON) The request parameter to create the Target Monitor and CustomerObserver. To be passed as a post parameter. It includes the following:

apiKey: The api key required to use this api. You will get this from a Gavagai operator. Note that the use of apiKey in the request is deprecated and the field will be removed in a future version but for now it is required.

userId: The user_id/username of the user for whom you wish to create the Target Monitor

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 just created. It contains the name, the id and the date created.

Example

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

                
{
  "apiKey" : "...",
  "userId" : "...",
  "targetTerms" : [ "...", "..." ],
  "language" : "CS",
  "name" : "...",
  "description" : "..."
}
Response
HTTP/1.1 201 Created
Content-Type: application/json

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

GET /documents

This method returns documents from the Ethersource document storage matching the provided search terms.

Request Parameters
name type description default constraints multivalued
exclude query An optional parameter. If excludeTerms is specified, only the documents that matches the terms argument AND any of the excludeTerms (AND any of the includeTerms) are valid as part of the return value of this method.     yes
include query An optional parameter. If includeTerms is specified, only the documents that matches the terms argument AND any of the includeTerms (AND any of the excludeTerms) are valid as part of the return value of this method.     yes
language query The language of the documents returned by this method, in ISO 639-1 two character format. EN "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
maxResults query The maximum number of documents in the result. 10 max: 100, min: 0 no
term query The search terms that make up the query. Note that a term may consist of several tokens, e.g., "a green apple".   max size: 100, min size: 1 yes
Response Body
media type data type description
application/json Documents (JSON) A Json structure containing the documents that matched the search terms.

Example

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

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

                
{
  "documentSnippets" : [ {
    "snippets" : [ "...", "..." ],
    "title" : "...",
    "url" : "..."
  }, {
    "snippets" : [ "...", "..." ],
    "title" : "...",
    "url" : "..."
  } ],
  "documentList" : {
    "documents" : [ {
      "rawText" : "...",
      "language" : "...",
      "url" : "...",
      "created" : { },
      "title" : "...",
      "sourceType" : "..."
    }, {
      "rawText" : "...",
      "language" : "...",
      "url" : "...",
      "created" : { },
      "title" : "...",
      "sourceType" : "..."
    } ],
    "totalNumberOfDocumentsInResult" : 12345
  }
}

POST /documents

This method returns documents from the Ethersource document storage matching the provided search terms.

Request Body
media type data type description
application/json DocumentsRequest (JSON) The document request
Response Body
media type data type description
application/json Documents (JSON) A Json structure containing the documents that matched the search terms.

Example

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

                
{
  "terms" : [ "...", "..." ],
  "includeTerms" : [ "...", "..." ],
  "excludeTerms" : [ "...", "..." ],
  "language" : "BM",
  "maxResults" : 12345
}
Response
HTTP/1.1 201 Created
Content-Type: application/json

                
{
  "documentSnippets" : [ {
    "snippets" : [ "...", "..." ],
    "title" : "...",
    "url" : "..."
  }, {
    "snippets" : [ "...", "..." ],
    "title" : "...",
    "url" : "..."
  } ],
  "documentList" : {
    "documents" : [ {
      "rawText" : "...",
      "language" : "...",
      "url" : "...",
      "created" : { },
      "title" : "...",
      "sourceType" : "..."
    }, {
      "rawText" : "...",
      "language" : "...",
      "url" : "...",
      "created" : { },
      "title" : "...",
      "sourceType" : "..."
    } ],
    "totalNumberOfDocumentsInResult" : 12345
  }
}

GET /findAllTargetTermsForUser

For a user who can be identified by his userId, this method returns all the target terms associated with that user. These are retrieved by first retrieving the CustomerObservers owned by this User, and from these CustomerObservers,get the target monitors associated with them. These are then used to retrieve the target parts(terms). The ids of these customerObservers are returned as well Example call: 

 https://ethersource.gavagai.se/ethersource/rest/v2/
 findAllTargetTermsForUser &apieKey=123ok&userId=admin

Request Parameters
name type description
userId query The user_id/username of the user for whom you wish to retrieve the target parts
Response Body
media type data type description
application/json EthersourceTargetResponse (JSON) A json object representing an targetTermsResponse. This will contain the number of targetTerms associated with the user, with the CustomerObserverId for these target Terms, along with the target terms themselves as well as the userId.

Example

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

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

                
{
  "userId" : "...",
  "targetDetails" : [ {
    "targetParts" : [ "...", "..." ],
    "targetName" : "...",
    "language" : "...",
    "customerObserverId" : 12345
  }, {
    "targetParts" : [ "...", "..." ],
    "targetName" : "...",
    "language" : "...",
    "customerObserverId" : 12345
  } ]
}

GET /findAssociations

Get associations for a CustomerObserver and a given date. The associations are terms which have co-occured with the terms of the CustomerObserver during the last 'windowSize' hours period that starts with the timestamp. The returned associations are grouped into topics. Each topic contains a list of associations that are similar to each other, and their associative strength. If a topic contains more than one member, all except one association contain a forWord, which point to the word that they are related to in the topic. The topic leader(associations which the topic is based on) contains no forWord.The topic name of each topic reflects the association which has the maximum strength from its topic members( the topic name reflects the Topic Leader)

Sample call: 

  https://ethersource.gavagai.se/ethersource/rest/v2/findAssociations?apiKey=apiKey123&customerObserverId=1&timestamp =2013-08-08%2000:00:00%20CEST&maxResults=30&backlogInDays=300&windowSize=1&userId=sampleUser

Request Parameters
name type description constraints
customerObserverId query The id of the customerObserver Of Interest. required
maxResults query The maximum number of associations you require. required
timestamp query The timestamp in the format 'yyyy-MM-dd HH:mm:ss z', for example, '2011-03-12 23:00:00 CEST', without the quotation marks.  
userId query The userId of the user accessing the method  
windowSize query The window size of the time range for which associations are of the query terms are required (in hours) required
Response Body
media type data type description
application/json Topics (JSON) A json object representing an associationsSearchResponse. This will contain a list of associationsTopics, which in turn contain associations, with the terms and their strength (and optionally a forWord), as well as the name of the CustomerObserver they were configured to.

Example

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

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

                
{
  "topics" : [ {
    "associations" : [ {
      "word" : "...",
      "strength" : 12345.0,
      "documentCount" : 12345,
      "forWord" : "..."
    }, {
      "word" : "...",
      "strength" : 12345.0,
      "documentCount" : 12345,
      "forWord" : "..."
    } ],
    "name" : "..."
  }, {
    "associations" : [ {
      "word" : "...",
      "strength" : 12345.0,
      "documentCount" : 12345,
      "forWord" : "..."
    }, {
      "word" : "...",
      "strength" : 12345.0,
      "documentCount" : 12345,
      "forWord" : "..."
    } ],
    "name" : "..."
  } ],
  "timestamp" : { },
  "observer" : {
    "id" : 12345,
    "name" : "...",
    "created" : { },
    "kpiId" : 12345
  }
}

GET /findAssociationsForWordsGeneric

For a specified set of target terms, this method returns teh words associated to those terms, along with the strength of association to each of these terms. These associations are calculated in real-time, for the day that the timestamp parameter specifies. The terms for which you would like the associations for must be specified, along with the language in which you would like the associations.If the user required simple merging, the individual associations for each of these terms are not returned, only the merged list it. If the user does not require simple merging, the associations for each of these terms is returned, along with three lists of merges associations, each list using a different algorithm for merging these associations. Example call:

https://ethersource.gavagai.se/ethersource/rest/v2/ findAssociationsForWordsGeneric ?apiKey=123ok&targetTerms=word1&targetTerms =word2&timestamp=2012-11-11+00: 00:00+CEST&maxResults=10&windowSize=1&isSimpleMerging=true 

 https://ethersource.gavagai.se/ethersource/rest/v2/
 findAssociationsForWordsGeneric
 ?language=EN&targetTerms=eur&targetTerms=usd
 &maxResults=0&windowSize=1&maxDfPerc
 =0&timestamp=2013-3-17%2011:23:54%20GMT& enableBigrams
 =false&enableNumberCoagulation=true& enableDocsCount=true&apiKey=abc123

Request Parameters
name type description default constraints multivalued
enableBigrams query If this is set to true, all bigrams in the associations retrieved will be grouped accordingly. This may be expensive.   required no
enableDocsCount query If this value is set to true, for each association retrieved, the number of documents in which this association appears, in the context specified by the target terms, filter query, timestamp, and language.   required no
enableNumberCoagulation query If this value is set to true, the number values in the associations are coagulated, ie, they are rounded of to 2 places of decimal and all of the same values are then merged together   required no
filterQuery query The Filter query by which you would like to filter your association. It should be in Lucene Syntax. Please ensure its correctness     no
language query The language in which you want associations for the entered target terms. If it is not specified, the topic filters will not function. EN "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
maxDfPerc query specifies how unique you would like the associations to be. Ranges from 0 - 99 (0 implies common associations, 99 implies extremely unique).   required no
maxResults query The maximum number of associations you would like returned for each term. To retrieve all associations, either specify as zero, or do not specify.   required no
targetTerms query The list of terms for which you would like the associations to be calculated.     yes
timestamp query The timestamp for which you would like associations. They will be calculated for a range of (timestamp - 1 day to timestamp). For simplicity, the timestamp will be rounded off to the previous hour.     no
windowSize query The window size of the time range considered for association calculation (in hours)   required no
Response Body
media type data type description
application/json EthersourceAssociationsForWordsResponse (JSON) A json object representing an associationsForWordsResponse. This will contain a list of associationsForWord, which in turn contains a list of associations for each word specified along with the word itself. Each of these associations contains the associated term and the strength (cos) of association. Apart from this, the response will also retrieve a merged list of associations, based on 3 different algorithms Example: {"associationsForWords":[{"word":"[word1, word2]","topics":[{ "associations" :[{"word":"Test","strength":0.5,"documentCount":null ,"forWord":null },{"word":"Test2","strength":0.1,"documentCount":null ,"forWord":null }],"name":"Topic1"},{"associations":[{"word":"Test3" ,"strength":0.6 ,"documentCount":null,"forWord":null},{"word":"Test4" ,"strength":0.2 ,"documentCount":null,"forWord":null}],"name":"Topic2" }]}],"timestamp":"2012-11-11 11:35:00 CET"} If simpleMerging is set to true, a different JSON is returned, only 1 list, which contains the merged associations, Example: {"associationsForWordsResponse":{"associationsForWords":{"word": "[word1, word2]" ,"associations":[{"association":"Test","strength": 0.5},{"association" :"Test2","strength":0.1},{"association":"Test3" ,"strength":0.6},{"association" :"Test4","strength":0.2}]},"timestamp" :"2012-11-10T23:00:00+01:00"}}

Example

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

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

                
{
  "associationsForWords" : [ {
    "topics" : [ {
      "associations" : [ { }, { } ],
      "name" : "..."
    }, {
      "associations" : [ { }, { } ],
      "name" : "..."
    } ],
    "word" : "..."
  }, {
    "topics" : [ {
      "associations" : [ { }, { } ],
      "name" : "..."
    }, {
      "associations" : [ { }, { } ],
      "name" : "..."
    } ],
    "word" : "..."
  } ],
  "timestamp" : { }
}

GET /findBackgroundAssociations

Get the background associations for a customerObserver for a particular timestamp, Using the 'backlog in days' specified, this method retrieves the associations that have the highest occurrence count from: (timestamp - backlogInDays) till timestamp, as well as the occurrence count.

Sample call: 

 https://ethersource.gavagai.se/ethersource/rest/v2/
 findBackgroundAssociations
 ?apiKey=apiKey123&customerObserverId=1&
 timestamp=2013-08-08%2000:00:00
 %20CEST&maxResults=30&backlogInDays=300

Request Parameters
name type description constraints
backlogInDays query The number of days to be considered while calculating background associations for the timestamp required
customerObserverId query The id of the customerObserver Of Interest. required
maxResults query The maximum number of associations you require. required
timestamp query The timestamp in the format 'yyyy-MM-dd HH:mm:ss z', for example, '2011-03-12 23:00:00 CEST', without the quotation marks.  
Response Body
media type data type description
application/json EthersourceBackgroundAssociationSearchResponse (JSON) A json object representing an backgroundAssociationSearchResponse. This will contain a list of backgroundAssociations, with the words and the occurrence counts, as well as the id of the CustomerObserver they were configured to.

Example

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

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

                
{
  "ethersourceBackgroundAssociations" : [ {
    "word" : "...",
    "strength" : 12345.0
  }, {
    "word" : "...",
    "strength" : 12345.0
  } ],
  "timestamp" : { },
  "customerObserverId" : 12345
}

GET /findDocumentDomains

Get Domains to the documents associated to a given CustomerObserverViewId and timestamp.

Once a point in time has been deemed interesting, either because of the raw signal associated with it (obtained with the getValue method), or because of the particular advice associated with it (obtained with the getTriggerMarkerMessage or getLatestTriggerMarkerMessage method), this method may be used to retrieve the Domains to the documents contributing to the signal/message at that particular time.

Request Parameters
name type description constraints multivalued
customerObserverViewId query The id of the customerObserverView. You will get this from a Gavagai operator. required no
pageSize query The maximal number of Domain URIs to get in a single call. This is an optional parameter. The default value is set to 500. required no
sortBy query This is an optional parameter. There are four sortable fields associated with a Domain URI: "value", "freq", "alphabetical"(without the quotation marks). Setting sortBy to "value" means that the Domain URIs are sorted according to the sum of all the polarization scores that their complete URIs contribute in descending order."alphabetical" sorts the URIs alphabetically. "freq" sorts the DomainsURIs according to the number of times pages from this domain have contributed to the pole/customerObserver.. The default value of sortBy is "freq", followed by a sub-sort by "value" Multiple sortBy arguments may be supplied in the same invocation.

Example. The call: 

            https://ethersource.gavagai.se/ethersource/rest/v2/
            findDocumentDomains
            ?apiKey=yourKey&customerObserverViewId=1&timestamp=2011
            -09-01%2001:01:00%20CEST&pageSize=100&sortBy
            =freq&sortBy=value

fetches the first 100 Domain URIs and returns them sorted according to the sum of the scores (highest scores first). The sort order within groups of URIs that have been assigned the same score is such that those with the highest frequency occur first.

  yes
startIndex query The index at which to start obtaining Domain URLs. This is an optional parameter. The default value is 0, which means that the URIs fetched will be from the start of the list (determined by the sortBy parameter). If you wish to skip, e.g., the first ten URIs in the list, startIndex should be set to 9. required no
timestamp query A timestamp in the format 'yyyy-MM-dd HH:mm:ss z', for example, '2011-03-12 23:00:00 CEST', for the time point of interest. The Domain URIs returned by this method are fetched from the time span decided by the timestamp and the resolution of the Customer Observer specified by the cusotmerObserverViewId. For instance, if the resolution is DAY, and the specified timestamp is as above, the URIs fetched will be from within the span 2011-03-12 00:00:00 CEST to 2011-03-12 23:59:59 CEST.   no
Response Body
media type data type description
application/json EthersourceDomainSearchResponse (JSON) A json object containing the configuration setting of the CustomerObserverView (the id, resolution, and windowSize, customerObserver and Curve id and names) as well as list of document Domains with information regarding each found Domain's URI, sum polarization score, frequency, the id of the pole from which the polarization score is calculated, as well as the total number of URIs returned.

Example

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

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

                
{
  "documentDomains" : [ {
    "documentDomain" : "...",
    "poleId" : 12345,
    "sumPolarizationScore" : 12345.0,
    "freq" : 12345
  }, {
    "documentDomain" : "...",
    "poleId" : 12345,
    "sumPolarizationScore" : 12345.0,
    "freq" : 12345
  } ],
  "customerObserverView" : {
    "id" : "...",
    "resolution" : "...",
    "windowSize" : 12345,
    "customerObserverName" : "...",
    "curveName" : "...",
    "customerObserverId" : 12345,
    "curveId" : 12345
  },
  "totalCount" : 12345
}

GET /findDocumentURIs

Get URIs to the documents associated to a given CustomerObserverViewId and timestamp.

Once a point in time has been deemed interesting, either because of the raw signal associated with it (obtained with the getValue method), or because of the particular advice associated with it (obtained with the getTriggerMarkerMessage or getLatestTriggerMarkerMessage method), this method may be used to retrieve the URIs to the documents contributing to the signal/message at that particular time.

Request Parameters
name type description constraints multivalued
customerObserverViewId query The id of the customerObserverView. You will get this from a Gavagai operator. required no
pageSize query The maximal number of URIs to get in a single call. This is an optional parameter. The default value is set to 500. required no
sortBy query This is an optional paramter. There are four sortable fields associated with a URI: "value", "date", "alphabetical", "pole" (without the quotation marks). Setting sortBy to "value" means that the URIs are sorted according to their polarization score in descending order. "date" sorts the URIs according to the time of processing, with the most recent URIs first in the list. "alphabetical" sorts the URIs alphapetically. "pole" sorts the URIs according to the attitudinal pole giving rise the score assigned to the URI. The default value of sortBy is "value". Multiple sortBy arguments may be supplied in the same invokation.

Example. The call: 

            https://ethersource.gavagai.se/ethersource/rest/v2/
            findDocumentURIs?apiKey=yourKey&customerObserverViewId=1
            &timestamp=2011-09-01 01:01:00
            CEST&pageSize=100&sortBy=value&sortBy=date

fetches the first 100 URIs and returns them sorted according to their scores (highest scores first). The sort order within groups of URIs that have been assigned the same score is such that recently processed URIs occur first.

  yes
startIndex query The index at which to start obtaining URLs. This is an optional parameter. The default value is 0, which means that the URIs fetched will be from the start of the list (determined by the sortBy parameter). If you wish to skip, e.g., the first ten URIs in the list, startIndex should be set to 9. required no
timestamp query A timestamp in the format 'yyyy-MM-dd HH:mm:ss z', for example, '2011-03-12 23:00:00 CEST', for the time point of interest. The URIs returned by this method are fetched from the time span decided by the timestamp and the resolution of the Customer Observer specified by the cusotmerObserverViewId. For instance, if the resolution is DAY, and the specified timestamp is as above, the URIs fetched will be from within the span 2011-03-12 00:00:00 CEST to 2011-03-12 23:59:59 CEST.   no
Response Body
media type data type description
application/json EthersourceURISearchResponse (JSON) A json object containing the configuration setting of the CustomerObserverView (the id, resolution, and windowSize, customerObserver and Curve id and names)) as well as list of document URIs with information regarding each found URI's processed date, URI, documentTitle, polarization score, the id of the pole from which the polarization score is calculated, as well as the total number of URIs returned. If the document does not have a title, no title is returned.

Example

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

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

                
{
  "documentUris" : [ {
    "documentUri" : "...",
    "documentTitle" : "...",
    "polarizationScore" : 12345.0,
    "date" : { },
    "poleId" : 12345,
    "mediaType" : "..."
  }, {
    "documentUri" : "...",
    "documentTitle" : "...",
    "polarizationScore" : 12345.0,
    "date" : { },
    "poleId" : 12345,
    "mediaType" : "..."
  } ],
  "customerObserverView" : {
    "id" : "...",
    "resolution" : "...",
    "windowSize" : 12345,
    "customerObserverName" : "...",
    "curveName" : "...",
    "customerObserverId" : 12345,
    "curveId" : 12345
  },
  "totalCount" : 12345
}

GET /findNumberOfDocumentsForWords

For a specified set of query terms, this method returns the number of documents which contain all these query terms. It returns the number of documents and also returns a copy of the parameters provided to the method. Example call: 

 https://ethersource.gavagai.se/ethersource/rest/v2/
 findNumberOfDocumentsForWords
 ?apiKey=123ok&targetTerms=test&timestamp=2012
 -11-11+00:00:00+CEST&windowSize=1

Request Parameters
name type description default constraints multivalued
filterQuery query     no
language query The language for which you require the document count EN "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
targetTerms query The list of terms which must be contained in the number of documents returned.     yes
timestamp query The timestamp (reduced to date) for which you would like the number of documents for the query terms.     no
windowSize query The window size of the time range for which the document count of the query terms are required (in hours)   required no
Response Body
media type data type description
application/json EthersourceDocumentCountResponse (JSON) A json object representing an documentCountResponse. This will contain the number of documents which contain the query terms along with the query terms themselves as well as the timestamp.

Example

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

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

                
{
  "numberOfDocuments" : 12345,
  "queryTerms" : [ {
    "termValue" : "..."
  }, {
    "termValue" : "..."
  } ],
  "timestamp" : { },
  "language" : "..."
}

GET /findSnippetsForAssociations

For an association and a set of target terms, this method returns snippets of documents which are most relevant to this association in the context of the target terms, for the timestamp specified. It returns the url, the source, the text, the created timestamp, language and relevance score of the document. The method also returns a copy of the parameters provided to the method. A maximum value of 200 can be specified for the number of documents to be returned, and a default value of 100 is taken if nothing, or 0 is specified. Example call: 

 https://ethersource.gavagai.se/ethersource/rest/v2/
 findSnippetsForAssociations
 ?apiKey=123ok&association=test1&targetTerms=test
 &maxResults=1&timestamp=2012-11-11+00:00:00+CEST&windowSize=1

Request Parameters
name type description default constraints multivalued
association query The association for which you would like the snippet.     no
filterQuery query The Filter query by which you would like to filter your documents. It should be in Lucene Syntax. Please ensure its correctness     no
language query The language in which you want documents for the entered target terms. If it is not specified, the topic filters will not function. EN "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
maxResults query The maximum number of documents you would like returned. A maximum value of 100 can be specified, and a default value of 100 is taken. One snippet will be retrieved per document.   required no
targetTerms query The list of targetTerms for which you would like the snippet.     yes
timestamp query The timestamp for which you would like snippets. They will be calculated for a range of (timestamp - 1 day to timestamp). For simplicity, the timestamp will be rounded off to the previous hour.     no
windowSize query The window size of the time range considered for document retrieval (in hours)   required no
Response Body
media type data type description
application/json EthersourceDocumentSnippetSearchResponse (JSON) A json object representing an documentSearchResponse. This will contain a list of the documents which contain the query terms along with the query terms themselves as well as the timestamp.

Example

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

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

                
{
  "documents" : [ {
    "rawText" : "...",
    "language" : "...",
    "source" : "...",
    "url" : "...",
    "score" : 12345.0,
    "created" : { },
    "snippetTokens" : [ {
      "snippetToken" : "...",
      "tags" : [ "...", "..." ]
    }, {
      "snippetToken" : "...",
      "tags" : [ "...", "..." ]
    } ]
  }, {
    "rawText" : "...",
    "language" : "...",
    "source" : "...",
    "url" : "...",
    "score" : 12345.0,
    "created" : { },
    "snippetTokens" : [ {
      "snippetToken" : "...",
      "tags" : [ "...", "..." ]
    }, {
      "snippetToken" : "...",
      "tags" : [ "...", "..." ]
    } ]
  } ],
  "numberOfDocuments" : 12345,
  "association" : "...",
  "timestamp" : { },
  "language" : "..."
}

GET /findSnippetsForURL

For a specified url, this method retrieves the relevant snippets for it. The complete documents are first retrieved, following which they are broken down into snippets based on the association and the target terms specified. These snippets are additionally broken down further, into portions which are either associations, target parts or neither, 

 https://ethersource.gavagai.se/ethersource/rest/v2/findSnippetsForURL?
 apiKey =123ok&association=test1&targetTerms=test&url=http://test.com

Request Parameters
name type description multivalued
association query The association for which you would like the snippet. no
targetTerms query The list of targetTerms for which you would like the snippet. yes
url query no
Response Body
media type data type description
application/json EthersourceURLSnippetSearchResponse (JSON) A json object representing an documentSnippetSearchResponse. This will return all snippets for the specified URL, as well as the language, and the timestamp.

Example

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

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

                
{
  "snippets" : [ {
    "snippet" : "...",
    "snippetTokens" : [ {
      "snippetToken" : "...",
      "tags" : [ "...", "..." ]
    }, {
      "snippetToken" : "...",
      "tags" : [ "...", "..." ]
    } ]
  }, {
    "snippet" : "...",
    "snippetTokens" : [ {
      "snippetToken" : "...",
      "tags" : [ "...", "..." ]
    }, {
      "snippetToken" : "...",
      "tags" : [ "...", "..." ]
    } ]
  } ],
  "url" : "...",
  "timestamp" : { },
  "language" : "..."
}

GET /getComparisonValues

For a specified number of CustomerObserverViewIds ( 2 to 10 ), all of which are owned by the user, this function retrieves the latest aggregated polarization value recorded over a range (windowSize*resolution) for each CustomerObserverView and packages all the data in a specific format. This format is specified to the function by the parameters clientType and widgetType. Each of these CustomerObserverViews must have the same resolution as well as the same window size, or an exception will be thrown. Example call: 

 https://ethersource.gavagai.se/ethersource/rest/v2/getComparisonValues?
 apiKey=123&COVIds=1&COVIds=2&clientType=GB&widgetType=
 GB_PIE_CHART

Request Parameters
name type description constraints multivalued
COVIds query The set of CustomerObserverViewIds you would like compared, all of these CustomerObserverViewIds must be specified as COVIds= "customerObserverViewID" .You will get these from a Gavagai operator. int yes
clientType query The type of Client for which the function must format the data. You must specify this. "GB" or "LT" no
widgetType query Given a client, the type of widget for which the function must format the data. You must specify this. "GB_FUNNEL_PLOT" or "GB_LINE_GRAPH" or "GB_PIE_CHART" or "GB_RAG_COLUMN" or "GB_TREND" or "LT_LINE_GRAPH" or "LT_PIE_CHART" no
Response Body
media type data type description
application/xml;charset="UTF-8" object An object of type javax.ws.rs.core.Response, which allows the method to dynamically determine the output format based on ClientType.

If clientType = GB and widgetType = GB_PIE_CHART, output will be

{ 23.8 FF0000 54.0 00FF00 }

If clientType = LT and widgetType = LT_PIE_CHART, output will be

{ {"chart":[{"name":"Obama","value":23.0},{"name":"Romney","value":14.0},{"name":"Others","value":2.0}]} }

Example

Request
GET /getComparisonValues
Content-Type: */*
Accept: application/xml;charset="UTF-8"

                
...
Response
HTTP/1.1 200 OK
Content-Type: application/xml;charset="UTF-8"

                
...

GET /getLatestTriggerMarkerMessage

Similar to getTriggerMarkerMessage except you get the latest available message.

Request Parameters
name type description constraints
sensorSubscriptionId query see getTriggerMarkerMessage required
Response Body
media type data type description
application/json EthersourceAdvice (JSON) see getTriggerMarkerMessage

Example

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

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

                
{
  "sensorSubscriptionId" : 12345,
  "adviceString" : "...",
  "timestamp" : { }
}

GET /getMostRecentValues

Request Parameters
name type description constraints
clientType query "GB" or "LT"
colour query  
customerObserverViewId query required
trendName query  
widgetType query "GB_FUNNEL_PLOT" or "GB_LINE_GRAPH" or "GB_PIE_CHART" or "GB_RAG_COLUMN" or "GB_TREND" or "LT_LINE_GRAPH" or "LT_PIE_CHART"
Response Body
media type data type description
application/xml;charset="UTF-8" object

Example

Request
GET /getMostRecentValues
Content-Type: */*
Accept: application/xml;charset="UTF-8"

                
...
Response
HTTP/1.1 200 OK
Content-Type: application/xml;charset="UTF-8"

                
...

GET /getTriggerMarkerMessage

Get the advice string (the message) for certain sensor subscription at a certain time.

In Ethersource the raw data (that may be retrieved by getValue) can be analyzed and presented as a recommendation or advice after being processed by the Ethersource evaluation algorithms. This may be a more easily accessible means to realize the potential of Ethersource signals. The contents of the message depend on the evaluation algorithm that is connected to the sensor subscription, you will have to get this format documentation independently of the current documentation.

The calling client must authenticate using a valid user and password with HTTP Basic authentication and must provide a valid apiKey which is owned by the authenticating user. The user must also own the sensor subscription. The method will retrieve a triggerMarker that matches the given timestamp and the resolution of the sensor. For example, given a timestamp of 2011-12-14 13:23:00 CES and a DAY resolution, the method will try to find a triggerMarker on the 14th of December. If the resolution is HOUR, the match would be made for hour 13 on the 14th of December. If the timestamp is too far away from any TriggerMarker the method will return nothing.

Example: 

     /ethersource/rest/v2/getTriggerMarkerMessage?apiKey=abc&sensorSubscriptionId=1&timestamp=2011-09-12 12:00:00 CEST

Request Parameters
name type description constraints
sensorSubscriptionId query is of a sensorSubscription owned by the authenticating user required
timestamp query a timestamp for which we want the matching TriggerMarker message  
Response Body
media type data type description
application/json EthersourceAdvice (JSON) the message of the triggermarker which is closest to the given timestamp within a period given by a starting time which is one sensor subscription resolution before and the end time which is one sensor subscription resolution after the timestamp respectively

Example

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

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

                
{
  "sensorSubscriptionId" : 12345,
  "adviceString" : "...",
  "timestamp" : { }
}

GET /getValue

Get raw Ethersource data for a certain CustomerObserverViewId and timestamp.

In Ethersource, a CustomerObserver monitors the calculations of a signal for a specific customer and for a certain subject, for example a signal concerning a subject such as 'Obama', as incoming data is processed from many different sources. The processed signal can be viewed in different resolutions (i.e. the rate at which the signal is calculated, this could be hourly, daily, etc) and each view of the signal is represented by a CustomerObserverView. The configuration of a CustomerObserver and its accompanying CustomerObserverViews is done by an administrator in Ethersource.

This method will allow a customer to retrieve a certain value for a CustomerObserverView. Since the resolution of the signal is given by the configuration on the server, the api only requires the id of the CustomerObserverView and a timestamp to be able to retrieve a correct value. The client must, however, know in advance the resolution of a given CustomerObserverView. This information is provided by an administrator, and it is also returned, along with the retrieved value itself, in each call to this method.

The values provided by this method are closing values. This means that a value for a certain period of time is calculated during the period and is not available until all underlying data for the period has been taken into account at the end of the period. For example, if the resolution of the view is 24 hours there will be at most one value per 24 hour period and each value will be calculated at the end of each 24 hour period. If a 24 hour period starts at 08:00 on June 2nd, 2011, the value for '2011-06-02 08:00' will be available at just after 08:00 on 3rd of June. If you try to retrieve a value before it has been calculated this method will return an error.

To retrieve any value you should call this method with the timestamp corresponding to the point in time for which you would like to retrieve a signal value. The calculated value, given the configured resolution, will be returned. If you do not know the resolution of a CustomerObserverView you can find it in the returned data after each call as it will always return the configuration information along with any value.

Example call: 

 https://ethersource.gavagai.se/ethersource/rest/v2/getValue?apiKey=123&
 amp; customerObserverViewId=2& timestamp=2011-03-12 23:12:00 CEST

(if you try this in a browser you may have to url-escape the timestamp parameter -- try putting a plus instead of space)

Request Parameters
name type description constraints
customerObserverViewId query The id of the customerObserverView. You will get this from a Gavagai operator. required
timestamp query A timestamp in the format 'yyyy-MM-dd HH:mm:ss z', for example, '2011-03-12 23:00:00 CEST', for the value of interest.  
Response Body
media type data type description
application/json EthersourceValue (JSON) A json object containing the configuration settings of the CustomerObserverView

Example

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

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

                
{
  "customerObserverView" : {
    "id" : "...",
    "resolution" : "...",
    "windowSize" : 12345,
    "customerObserverName" : "...",
    "curveName" : "...",
    "customerObserverId" : 12345,
    "curveId" : 12345
  },
  "value" : "...",
  "timestamp" : { }
}

GET /getValues

Given two different timestamps, get all possible aggregated values from Ethersource data for a specified resolution between those two time stamps for a certain CustomerObserverViewId.

In Ethersource, a CustomerObserver monitors the calculations of a signal for a specific customer and for a certain subject, for example a signal concerning a subject such as 'Obama', as incoming data is processed from many different sources. The processed signal can be viewed in different resolutions (i.e. the rate at which the signal is calculated, this could be hourly, daily, etc) and each view of the signal is represented by a CustomerObserverView. The configuration of a CustomerObserver and its accompanying CustomerObserverViews is done by an administrator in Ethersource.

This method will allow a customer to retrieve a set of values for a CustomerObserverView, within the specified time range.Since the resolution of the signal is given by the configuration on the server, the api only requires the id of the CustomerObserverView and the timestamps between which the data is required to be able to retrieve a correct values. The client must, however, know in advance the resolution of a given CustomerObserverView. This information is provided by an administrator,and it is also returned, along with the retrieved values themselves,in each call to this method.

The specified time range is broken down into smaller periods of time, based on the resolution, and each of these periods corresponds to a return value. The values provided by this method are closing values. This means for each of the values which are returned, within that time range, the value for a certain period of time is calculated during the period and is not available until all underlying data for the period has been taken into account at the end of the period. For example, if the resolution of the view is 24 hours there will be at most one value per 24 hour period and each value will be calculated at the end of each 24 hour period. If a 24 hour period starts at 08:00 on June 2nd, 2011, the value for '2011-06-02 08:00' will be available at just after 08:00 on 3rd of June. If you try to retrieve values before they have been calculated this method will return an error.

To retrieve a set of values you should call this method with the timestamps corresponding to the range in time for which you would like to retrieve the signal values. The calculated values, given the configured resolution, will be returned. If you do not know the resolution of a CustomerObserverView you can find it in the returned data after each call as it will always return the configuration information along with any value.

Example call: 

 https://ethersource.gavagai.se/ethersource/rest/v2/getValues?apiKey=123&
 amp; customerObserverViewId=2&timestampBegin=2011-03-10 23:12:00
 CEST&timestampEnd=2011-03-12 23:12:00 CEST

(if you try this in a browser you may have to url-escape the timestamp parameters -- try putting a plus instead of space)

If, in the timerange, at least one of the timestamps has data,instead of throwing an exception, the timestamps not having data are omitted. On the other hand, if none of the timestamps have any data associated with them, a NO_DATA exception is thrown.

For this method call, there is a MINUTES_DELAY of 15 minutes, meaning that the client must wait 15 minutes after the timestamp has passed, to retrieve a value for that timestamp.

Request Parameters
name type description constraints
customerObserverViewId query The id of the customerObserverView. You will get this from a Gavagai operator. required
timestampBegin query A timestamp in the format 'yyyy-MM-dd HH:mm:ss z', for example, '2011-03-12 23:00:00 CEST', which would be the time from which you want values for.  
timestampEnd query A timestamp in the format 'yyyy-MM-dd HH:mm:ss z', for example, '2011-03-12 23:00:00 CEST', which would be the timestamp until which you want vales for.  
Response Body
media type data type description
application/json EthersourceValues (JSON) A json object containing the configuration settings of the CustomerObserverView (the id, name, resolution, and window size (number of units of the given resolution), customerObserver and Curve id and names), and the values corresponding to each corresponding timestamp within the time stamp range as a floating number,along with the number of values returned.

Example

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

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

                
{
  "customerObserverView" : {
    "id" : "...",
    "resolution" : "...",
    "windowSize" : 12345,
    "customerObserverName" : "...",
    "curveName" : "...",
    "customerObserverId" : 12345,
    "curveId" : 12345
  },
  "values" : [ {
    "value" : 12345.0,
    "timestamp" : { },
    "quote" : "..."
  }, {
    "value" : 12345.0,
    "timestamp" : { },
    "quote" : "..."
  } ],
  "numberOfValues" : 12345
}

GET /getValuesMultiple

Given two different timestamps, get all possible aggregated values from Ethersource data for a specified resolution between those two time stamps for a specified set of customerObserverViewIds.

In Ethersource, a CustomerObserver monitors the calculations of a signal for a specific customer and for a certain subject, for example a signal concerning a subject such as 'Obama', as incoming data is processed from many different sources. The processed signal can be viewed in different resolutions (i.e. the rate at which the signal is calculated, this could be hourly, daily, etc) and each view of the signal is represented by a CustomerObserverView. The configuration of a CustomerObserver and its accompanying CustomerObserverViews is done by an administrator in Ethersource.

This method will allow a customer to retrieve a set set of values, for each of the customerObserverViews corresponding to the Ids specified by the user, within the specified time range. Since the resolution of the signal is given by the configuration on the server, the api only requires the id of the CustomerObserverView and a timestamps between which the data are required to be able to retrieve a correct values. The client must, however, know in advance the resolution of each CustomerObserverView. This information is provided by an administrator,and it is also returned, along with the retrieved values themselves,in each call to this method.

The specified time range is broken down into smaller periods of time, based on the resolution, and each of these periods corresponds to a return value. The values provided by this method are closing values. This means for each of the values which are returned, within that time range, the value for a certain period of time is calculated during the period and is not available until all underlying data for the period has been taken into account at the end of the period. For example, if the resolution of the view is 24 hours there will be at most one value per 24 hour period and each value will be calculated at the end of each 24 hour period. If a 24 hour period starts at 08:00 on June 2nd, 2011, the value for '2011-06-02 08:00' will be available at just after 08:00 on 3rd of June. If you try to retrieve a values before they have been calculated this method will return an error.

To retrieve a set of values you should call this method with the timestamps corresponding to the range in time for which you would like to retrieve the signal values. The calculated values, given the configured resolution, will be returned. If you do not know the resolution of a CustomerObserverView you can find it in the returned data after each call as it will always return the configuration information along with any value.

Example call: 

 https://ethersource.gavagai.se/ethersource/rest/v2/getValuesMultiple?
 apiKey= 123&
 customerObserverViewId=2&customerObserverViewId=3&
 timestampBegin=2011-03-10 23:12:00 CEST&timestampEnd=2011-03-12
 23:12:00 CEST

(if you try this in a browser you may have to url-escape the timestamp parameters -- try putting a plus instead of space)

Request Parameters
name type description constraints multivalued
customerObserverViewId query The set of customerObserverViewIds. You will get this from a Gavagai operator. int yes
timestampBegin query A timestamp in the format 'yyyy-MM-dd HH:mm:ss z', for example, '2011-03-12 23:00:00 CEST', which would be the time from which you want values for.   no
timestampEnd query A timestamp in the format 'yyyy-MM-dd HH:mm:ss z', for example, '2011-03-12 23:00:00 CEST', which would be the timestamp until which you want vales for.   no
Response Body
media type data type description
application/json array of EthersourceValues (JSON) A json array which contains a JSON object corresponding to each of the customerObserverViewIds supplied, containing the configuration settings of the CustomerObserverView (the id, name, resolution, and window size (number of units of the given resolution), customerObserver and Curve id and names), and the values corresponding to each corresponding timestamp within the time stamp range as a floating number,along with the number of values returned.

Example

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

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

                
[ {
  "customerObserverView" : {
    "id" : "...",
    "resolution" : "...",
    "windowSize" : 12345,
    "customerObserverName" : "...",
    "curveName" : "...",
    "customerObserverId" : 12345,
    "curveId" : 12345
  },
  "values" : [ {
    "value" : 12345.0,
    "timestamp" : { },
    "quote" : "..."
  }, {
    "value" : 12345.0,
    "timestamp" : { },
    "quote" : "..."
  } ],
  "numberOfValues" : 12345
} ]

GET /languages

This method returns all supported languages

Response Body
media type data type description
application/json array of Language (JSON) A json containing the languages

Example

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

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

                
"AA"

GET /listAllCustomerObserverViews

For an authenticated user, this method returns all the CustomerObserverViews the user owns, including the name of the CustomerObserver and Curve to which it is configured: 

 https://ethersource.gavagai.se/ethersource/rest/v2/
 listAllCustomerObserverViews?apiKey=123ok

Response Body
media type data type description
application/json ListCustomerObserverViewsResponse (JSON) A json containing customerObserverViews owned by the authenticated user, as well as the above mentioned details

Example

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

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

                
{
  "customerObserverViews" : [ {
    "id" : "...",
    "resolution" : "...",
    "windowSize" : 12345,
    "customerObserverName" : "...",
    "curveName" : "...",
    "customerObserverId" : 12345,
    "curveId" : 12345
  }, {
    "id" : "...",
    "resolution" : "...",
    "windowSize" : 12345,
    "customerObserverName" : "...",
    "curveName" : "...",
    "customerObserverId" : 12345,
    "curveId" : 12345
  } ],
  "userId" : "..."
}

GET /pingService

Check service is up

Response Body
media type data type description
application/json HealthCheckReport (JSON) an object of the type HealthCheckReport containing results from all the contained health checks. Currently, there are the following health checks:

  • DB_CHECK_TIMESTAMP: a simple db query to find the current time of the db server and compare it to the current time of the client server.

Example

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

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

                
{
  "healthCheckResults" : [ {
    "healthCheckType" : "GET_BOOKMARKS",
    "healthy" : true,
    "responseTimeMillis" : 12345
  }, {
    "healthCheckType" : "CACHE_SERVICE_CHECK",
    "healthy" : true,
    "responseTimeMillis" : 12345
  } ],
  "healthy" : true,
  "totalResponseTimeMillis" : 12345
}

GET /suggestSalientTerms

For an authenticated user, this method returns suggestions based on the relevant and irrelevant document urls The suggestions will not include terms The returned disambiguationIncludeTerms will not include existingIncludeTerms The returned disambiguationExcludeTerms will not include existingExcludeTerms

Request Parameters
name type description default constraints multivalued
existingExcludeTerms query The target terms that will be filtered from the returned suggestions   max size: 75, min size: 0 yes
existingIncludeTerms query The target terms that will be filtered from the returned suggestions   max size: 75, min size: 0 yes
irrelevantUrls query The urls to documents the user found irrelevant   max size: 30, min size: 0 yes
language query The language of the specified terms (In ISO 639-1 language code format) EN "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
maxResult query The maximum suggestions returned 20 max: 100, min: 1 no
relevantUrls query The urls to documents the user found relevant   max size: 30, min size: 0 yes
terms query The target terms that will be filtered from the returned suggestions   max size: 75, min size: 1 yes
Response Body
media type data type description
application/json SalientTerms (JSON) A json containing the suggestions

Example

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

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

                
{
  "disambiguationIncludeTerms" : [ "...", "..." ],
  "disambiguationExcludeTerms" : [ "...", "..." ]
}

GET /suggestTerms

For an authenticated user, this method returns suggestions containing for terms which are related to the terms entered by the user.The possible types of suggestions that can be retrieved are: PARADIGMATIC_NEIGHBOUR, SYNTAGMATIC_NEIGHBOUR, ASSOCIATION, FILTERED_STARTS_WITH, STARTS_WITH, STRING_SIMILAR, AT_MENTION, HASH_TAG.

If no suggestions are specified, the default suggestions are returned, ie : PARADIGMATIC_NEIGHBOUR, SYNTAGMATIC_NEIGHBOUR, FILTERED_STARTS_WITH, STARTS_WITH, STRING_SIMILAR, AT_MENTION, HASH_TAG.

Below is a description of the suggestions.

PARADIGMATIC_NEIGHBOUR: Words that can replace the forWord. Strength corresponds to the cos result between the two words.

SYNTAGMATIC_NEIGHBOUR: Words that occur next to the forWord. Strength corresponds to the cos result between the two words.

ASSOCIATION: Words that occur near to the forWord. Strength corresponds to the cos result between the two words.

FILTERED_STARTS_WITH: Words that start with the forWord and can replace the forWord. Strength corresponds to the frequency of the word.

STARTS_WITH: Words that start with the forWord. Strength corresponds to the frequency of the word.

STRING_SIMILAR: Words that are textually similar to the forWord and can replace the forWord. Strength corresponds to textual distance between the words.

AT_MENTION: At-mention forms of the input words. Strength is irrelevant.

HASH_TAG: Hash tag forms of the input words. Strength is irrelevant.

Request Parameters
name type description default constraints multivalued
language query The language of the specified terms (In ISO 639-1 language code format) EN "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
suggestionType query The types of suggestions required by the api.   "ASSOCIATION" or "AT_MENTION" or "FILTERED_STARTS_WITH" or "HASH_TAG" or "PARADIGMATIC_NEIGHBOUR" or "STARTS_WITH" or "STRING_SIMILAR" or "SYNTAGMATIC_NEIGHBOUR" yes
terms query The terms for which you would like suggestions which are related terms   max size: 150, min size: 1 yes
Response Body
media type data type description
application/json Suggestions (JSON) A json containing the suggestions for the terms (grouped by the relation to the related term itself).

Example

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

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

                
{
  "paradigmaticNeighbours" : [ {
    "word" : "...",
    "forWord" : "...",
    "strength" : 12345.0
  }, {
    "word" : "...",
    "forWord" : "...",
    "strength" : 12345.0
  } ],
  "syntagmaticNeighbours" : [ {
    "word" : "...",
    "forWord" : "...",
    "strength" : 12345.0
  }, {
    "word" : "...",
    "forWord" : "...",
    "strength" : 12345.0
  } ],
  "associations" : [ {
    "word" : "...",
    "forWord" : "...",
    "strength" : 12345.0
  }, {
    "word" : "...",
    "forWord" : "...",
    "strength" : 12345.0
  } ],
  "stringSimilarTerms" : [ {
    "word" : "...",
    "forWord" : "...",
    "strength" : 12345.0
  }, {
    "word" : "...",
    "forWord" : "...",
    "strength" : 12345.0
  } ],
  "startsWithTerms" : [ {
    "word" : "...",
    "forWord" : "...",
    "strength" : 12345.0
  }, {
    "word" : "...",
    "forWord" : "...",
    "strength" : 12345.0
  } ],
  "atMentionTerms" : [ {
    "word" : "...",
    "forWord" : "...",
    "strength" : 12345.0
  }, {
    "word" : "...",
    "forWord" : "...",
    "strength" : 12345.0
  } ],
  "hashTagTerms" : [ {
    "word" : "...",
    "forWord" : "...",
    "strength" : 12345.0
  }, {
    "word" : "...",
    "forWord" : "...",
    "strength" : 12345.0
  } ],
  "filteredStartsWithTerms" : [ {
    "word" : "...",
    "forWord" : "...",
    "strength" : 12345.0
  }, {
    "word" : "...",
    "forWord" : "...",
    "strength" : 12345.0
  } ]
}

GET /textPolarization

Get polarization scores for a text fragment visavi a set of predefined poles of interest.To Purchase the poles which you would like to access, please contact a Gavagai operator

Request Parameters
name type description constraints multivalued
polarizationAlgorithm query The algorithm using which you would like to polarize "DISTANCE" or "EXACTSKIPAMPLIFY" or "LEGACY" no
poleId query A list of Long variables specifying the poleIds for which you want your fragment polarized.Note that you must have subscribed to these poles to analyse your text based on them. long yes
textFragment query The bit of text you intend to polarize.   no
wordSpaceId query The id of the WordSpace against which you would like your fragment analysed. required no
Response Body
media type data type description
application/json PolarizationValue (JSON) A json object with a series of float scores for the poles under consideration,

Example

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

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

                
{
  "value" : [ "...", "..." ],
  "text" : "..."
}

POST /uploadImage

For the topic tracker admin, this method allows the user to upload any image to Gavagai servers and the user is given the Url to the image.

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

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

Request Body
media type data type description
application/json ImageUploadRequest (JSON) The request parameter to save the image in Gavagai's servers. To be passed as a post parameter. It includes the following:

apiKey: The api key required to use this api. You will get this from a Gavagai operator. Note that the use of apiKey in the request is deprecated and the field will be removed in a future version but for now it is required.

title: The title of the image

description: The description of the image

data: The encoded image data in base64 encoding as a string

Response Body
media type data type description
application/json ImageUploadResponse (JSON) A JSON containing the URl of the image just saved.

Example

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

                
{
  "apiKey" : "...",
  "title" : "...",
  "description" : "...",
  "data" : "..."
}
Response
HTTP/1.1 201 Created
Content-Type: application/json

                
{
  "url" : "..."
}