Silobreaker Api Reference

Index

Login

Logout

Categories from Document

DocumentCount

Document Search

Document volume

Comments from Document

Attachments from Document

Keywords from Document

Categories from Document

Entities

Entities from Documents

Entity Graph

Entity Search

Entity Reference

Evidence

GeoEvents

Get Image accessible by User

Project Item (Add)

Project Item (Remove)

Project Item (Exist)

Project (Get)

Project (Add)

Secure Content

Term (Add)

Term (Request)

Term (Check)

Top Stories

Metasearch

Mypage widget

MypageTab

Save Widget

UpdateTabLayout

Authentication

A request to the API must be authenticated, either by using a key, or by having a valid session cookie set. If no key is provided, and no cookie is set, it is interpreted as the key being set to the empty string. The key is set by adding the parameter “apiKey” to the url.

Keys may require a digest to ensure that the request is valid. This is provided by adding the parameter “digest” to the url. When using the api through an external service, this service will have to calculate the digest if it is required. This is done by using a shared secret key that is provided when the apiKey is acquired. The digest is calculated as described by the following pseudo-code:

Key = "MySharedKey"

UTF8Key = UTF8Encode(Key)

// This is a HTTP GET request
Message = "GET http://www.example.com/documents/Sweden"

UTF8Message = UTF8Encode(Message)

// Will output Gh9YtyvJvF39Isfn9QFo2nNkQkI=
Signature = Base64(HMAC-SHA1(UTF8Message, UTF8Key));

The final request will look like:

http://www.example.com/documents/Sweden?apiKey=MyApiKey&digest=Gh9YtyvJvF39Isfn9QFo2nNkQkI%3D

See login for further details on how to authenticate a user via the API.

Response Types

The API supports several of response format types. The most common ones are Xml and Json which both can be used for all requests. Other more specialised formats are Atom 1.0 and Html which can be used for document list results. To switch response type, simply set parameter “type” to the desired format. Example : /documents/United Nations?type=atom10.

The following formats are supported:

API Methods

Login

Sets a session cookie which authenticates further calls to the API.

Note : This method only supports json and jsonp, which must be explicitly called with the parameter type.

url
/login

Parameters

username
Username
password
Password

Returns a JSON object containing a status message and the name of the session cookie.

Logout

Logouts the current user if a session cookie is set.

Note : This method only supports json and jsonp, which must be explicitly called with the parameter type.

url
/logout

LoginStatus

Returns authentication state, either Status: authenticated or Status: unauthenticated.

Note : This method only supports json and jsonp, which must be explicitly called with the parameter type.

url
/loginStatus

Categories from Document

Get the related categories from a query

url
/documents/categories{parameters}

Parameters

q
The query string to search for.
types (optional)
Filter on the type of entities
entityTypeLimits (optional)
Filter the maximum number of entities for each type that will be included in the result.
optimization (optional)
Optimisation can be used by using one of the following keywords:

DocumentCount

url
/documentCount{parameters}

Parameters

q
The query string to search for.
splitType (optional)
One of the following split types can be used. If none is selected the manual split type will be used.
showDuplicates (bool)
Indicate if the count should be distinct or not.

Document search

Gets the latest documents or documents matching a query.

url
/documents{parameters}
/documents/{parameters}
/documents/{query}/{types}{parameters}

Parameters

q
The query string to search for.
types
Comma separated list of document types that should be returned.
Valid types are:
pageSize
Number of documents to return. Default is 10.
pagenumber
Window the result to a specific page. First page is 0.
sortBy
How the result should be sorted. Default is by publication date. The following sort values are supported:
sortDirection
Which direction the list should be sorted
rel
Set the relevance threshold for the document search. The level can be set between 0.0 - 1.0. Only documents with a relevancy level above the threshold will be returned - in other words, the higher the number, the heavier the results will be filtered. A low number will give more results but might include results of only peripheral interest.
extras
Provides extra data to each result row. The following values are supported (and can be combined as a comma separated list):

Example

Return the 5 most relevant blogs mentioning “United Nations”. This can be requested using the following uri: 

/documents?q=United Nations&types=blog&pageSize=5&sortBy=relevance

The result can look like this:

<?xml version="1.0" encoding="utf-16"?>
<ResultList xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
  <Items>
    <DocumentData>
      <Id>5_2261700798855512087</Id>
      <Description>NYT's Krugman: Hopefully, 'Globalization 2.0' will fare better than 1.0</Description>
      <Type>Blog</Type>
      <PublicationDate>2008-12-22T14:19:00Z</PublicationDate>
      <Publisher>BloggingStocks</Publisher>
    </DocumentData>
    <DocumentData>
      <Id>5_2261700811388092416</Id>
      <Description>US Refuses to Sign UN Resolution on Gay Rights [Dispatches from the Culture Wars]</Description>
      <Type>Blog</Type>
      <PublicationDate>2008-12-22T14:31:00Z</PublicationDate>
      <Publisher>ScienceBlogs : Combined Feed</Publisher>
    </DocumentData>
    <DocumentData>
      <Id>5_2261701110693625856</Id>
      <Description>Michealene Cristini Risley: "A Christmas Carol in Zimbabwe"</Description>
      <Type>Blog</Type>
      <PublicationDate>2008-12-22T18:53:00Z</PublicationDate>
      <Publisher>The Huffington Post Full Blog Feed</Publisher>
    </DocumentData>
    <DocumentData>
      <Id>5_2261701122454454272</Id>
      <Description>The protectionism comeback and a possible solution</Description>
      <Type>Blog</Type>
      <PublicationDate>2008-12-22T19:00:00Z</PublicationDate>
      <Publisher>The Curious Capitalist - TIME.com</Publisher>
    </DocumentData>
    <DocumentData>
      <Id>5_2261701122940993536</Id>
      <Description>Allan Clear: Harm Reduction and Allan's Diplomatic Faux Pas, on the Final Day of the U.N. Drug Treatment Conference, Vienna</Description>
      <Type>Blog</Type>
      <PublicationDate>2008-12-22T19:01:00Z</PublicationDate>
      <Publisher>The Huffington Post Full Blog Feed</Publisher>
    </DocumentData>
  </Items>
  <TotalCount>1093</TotalCount>
</ResultList>

Document volume

Get document volume result based on a document query.

url
/documentvolume{parameters}
/documentvolume/{parameters}

Parameters

q
The query string to search for.
binSize
Defaults to 1440
startDate
The datetime should be in yyyy-MM-dd hh:mm:ss format
endDate
The datetime should be in yyyy-MM-dd hh:mm:ss format
splitType (optional)
One of the following split types can be used. If none is selected the manual split type will be used.

Comments from Document

Get all comments from a certain document.

url
/document/comments{parameters}

Parameters

docId (itemRef)
Document that the comments are based on

Attachments from Document

Get all attachments from a certain document.

url
/document/attachments{parameters}

Parameters

docId (itemRef)
Document that the attachments are attached to

Keywords from Document

Get all user specified keywords from a certain document.

url
/document/keywords{parameters}

Parameters

docId (itemRef)
Document that the attachments are attached to

Categories from Document

Get all user specified categories from a certain document.

url
/document/categories{parameters}

Parameters

docId (itemRef)
Document that the attachments are attached to

Entities

Searches for entities using the supplied query.

url
/entities
/entities/{query}
/entities/{query}/{types}

Parameters

q
The query string to search for.
types
A comma separated list of type strings.
rel (double)
Relevance value
extras
Provides extra data to each result row. The following values are supported (and can be combined as a comma separated list):

Entities from Documents

Get the related terms from a query.

url
/documents/entities{parameters}
/documents/{query}/entites
/documents/{query}/entites/{types}

Parameters

q
The query string to search for.
types (optional)
Filter on the type of entities
Valid types are:
entityTypeLimits (optional)
Filter the maximum number of entities for each type that will be included in the result.
optimization (optional)
Optimisation can be used by using one of the following keywords:

Entity Graph

url
/entitygraph/{query} - gets an entity graph based on a query string.
/entitygraph/{query}/{types} - gets and entity graph containing only specific entity types. Multiple types can be separated by commas.
Valid types are:

Parameters

noNodes
Number of nodes to return. Default is 20.
graphEntities
List of entities that should be included in the graph. Entities are referenced with ids and separated by commas.
entityTypeLimits
Maximum number of entities for each type that will be included in the graph. Must be combined with {types} parameter.
expandEntities
Entities that will be included and expanded in the graph.

Entity search

Entities are always sorted by relevance with most relevant entity first.

url
/entities - searches for entities matching a query string.

Parameters

q
The query string to search for.
types
Comma separated list of entity types that should be returned.
Valid types are
pageSize
Number of entities to return. Default is 20.
pageNumber
Window the result to a specific page. First page is 0.

Example

Return the 5 most relevant entities having Obama in its name. This can be requested using this URI: 

/entities?q=Obama&pageSize=5

This can give the following result.

<?xml version="1.0" encoding="utf-16"?>
<ResultList xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
  <Items>
    <TermData>
      <Id>11_98035</Id>
      <Description>Obama (Japan)</Description>
      <Type>City</Type>
    </TermData>
    <TermData>
      <Id>11_8081593</Id>
      <Description>Michelle Obama</Description>
      <Type>Person</Type>
    </TermData>
    <TermData>
      <Id>11_11332962</Id>
      <Description>Hussein Obama</Description>
      <Type>Person</Type>
    </TermData>
    <TermData>
      <Id>11_46954190</Id>
      <Description>Natasha Obama</Description>
      <Type>Person</Type>
    </TermData>
    <TermData>
      <Id>11_240886</Id>
      <Description>Barack Obama</Description>
      <Type>Person</Type>
    </TermData>
  </Items>
  <TotalCount>516</TotalCount>
</ResultList>

Entity Reference

url
/entity
/entity/{entityReference}

Parameters

entityReference
A reference to the entity
extras
Provides extra data to each result row. The following values are supported (and can be combined as a comma separated list):

Evidence

Extracts an evidence snippet from recent news - a short piece of text displaying the supplied entity in context in an article.

url
/evidence
/evidence/{entityReference}

Parameters

entityReference
A reference to the entity
extras
Provides extra data to each result row. The following values are supported (and can be combined as a comma separated list):

—

Get Image accessible by User

Resolves a image connected to the user given a description and category. Only supports png type!

url
/Image

Parameters

Category
The category type of the image. Images are saved into different category bins.
Desc (filename)
The image description which it will resolve from.

GeoEvents

Gets news that are geotagged. If no coordinates are given to the api call it’ll search globally otherwise it is possible to specify a certain area with the lat/long parameters.

url
/geoEvents
/geoEvents/{query}

Parameters

q
The query string to search for.
minNoDoc (int)
Not implemented at the moment.
maxNoVisibleEvent (int)
Max number of events that will be returned.
minLat (double)
Minimum latitude value allowed for the geotagged news.
maxLat (double)
Maximum latitude value allowed for the geotagged news.
minLong (double)
Minimum longitude value allowed for the geotagged news.
maxLong (double)
Maximum longitude value allowed for the geotagged news.

Add Item to Project

Add an item to a specific project

url
/project/AddItem

Parameters

Description (Optional if ProjectRef is used.)
Description of project to add item to.
ProjectRef (Optional if Description is used)
ItemRef of the project.
ProjectType
Choose from one of the following: “EntityList”, “Scrapbook”, “MyPageTab”
ItemRef
The item to be added: itemclass_itemId
MayCreateProject (Optional, requires Description parameter)
If project doesn’t exist create one and add the item into the new project

Remove an item from a Project

Remove an existing item from a project

url
/project/RemoveItem

Parameters

Description
Project description to add to
ProjectRef
ItemRef of the project.
ProjectType
Choose from one of the following: “EntityList”, “Scrapbook”, “MyPageTab”
ItemRef
The item to be removed: itemclass_itemId

Get Projects with item

List all projects that contains the given item

url
/projects/WithItem

Parameters

Description
Project description to add to
ProjectType
Choose from one of the following: “EntityList”, “Scrapbook”, “MyPageTab”
ItemRef
The item to be searched for: itemclass_itemId

Get MyList and Saved articles

Lists all collections/lists for the calling user.

url
/projects{parameters}
/projects/{ProjectType}/{parameters}

Parameters

usePersistentStorage (optional)
Boolean value if the system should use persistent storage when retrieving the lists.
ProjectType (optional)
Choose from one of the following: “EntityList”, “Scrapbook”, “MyPageTab”

Create MyList or Saved article

A modifying api call that adds a collection/list to the calling user. The description must be unique per collection/list. If successful the collection/list will be returned.

url
/project/Add{parameters}
/project/Add/{ProjectType}/{parameters}

Parameters

Description
The descripition of the project must be unique per project type, for the current user.
ProjectType
Choose from one of the following: “EntityList”, “Scrapbook”, “MyPageTab”
usePersistentStorage (optional)
Boolean value if the system should use persistent storage when retrieving the lists.

Secure Content

Check access on requested content using configuration.

Possible keys

url
/Widget/{key}

Create Term

url
/term/add/{parameters}

Parameters

description
term description, must be system unique
termType
Allowed term types are *City *Organization *Person *Company *Site *Product *Publisher *Journalist *Keyphrase
lang
Language ISO code i.e sv, en.

Request Term

url
/term/request/{parameters}

Parameters

description
term description, must be system unique
termType
Allowed term types are *City *Organization *Person *Company *Site *Product *Publisher *Journalist *Keyphrase
comment
user comment that will be sent to developers
lang
Language ISO code i.e sv, en.

Term Availability

Check if it is possible to create a term with the given description. The term type can be specified as well to see if there is a duplicate or just conflicting term description.

url
/term/availability/{parameters}

Parameters

description
term description, must be system unique
termType
Allowed term types are *City *Organization *Person *Company *Site *Product *Publisher *Journalist *Keyphrase

Top Stories

url
/topstories - gets today’s top stories.
/topstories/{query} - gets the top stories related to a query string.

Parameters

q
The query string to search for.
noStories
Number of stories to return. Default is 5.
minRelevance
The minimum relevance for a story to be included in the result. The relevance value should be somewhere between 0 and 1, where 1 means very relevant and indicates a story having documents only mentions the query itself and nothing else. Default is approximately 0.1
minNoDocuments
The minimum number of documents that a story should consist of. Default is 2.
storySelector (optional)
Choose what type of algorithm should be used to order the stories.
extras
Provides extra data to each result row. The following values are supported (and can be combined as a comma separated list):

Metasearch

Searches through three different providers twitter, google blogs and Facebook. Per default all providers are used, to specify a specific provider use the parameter providers and the following provider key:

url
/meta{parameters}
/meta/{query}/{providers}

Parameters

q
The query string to search for.
providers (optional)
Which providers to search within
languages (optional)
set a language iso code
example

https://api.silobreaker.com/meta/?q=Silobreaker&type=json

Mypage widget

This is used for the RSS feed on mypage widgets. In order to use this api call the widget id must be specified and only digested api keys are accepted.

url
/mypagewidget{parameters}

Parameters

wid
Widget id
extras
Provides extra data to each result row. The following values are supported (and can be combined as a comma separated list):

MypageTab

You can list all the widgets for a specific MyPage Tab. Either supply a tab Id or projectId.

Note : This method only supports json and jsonp, which must be explicitly called with the parameter type.

url
/mypagetab{parameter}

Parameters

type
json or jsonp, must be specified.
tabId
A unique Tab id.
projectId
A unique projectId for the tab.

UpdateTabLayout

Use this method to update the layout on the MyPage tab.

Note : This method only supports json and jsonp, which must be explicitly called with the parameter type.

url
/updateTabLayout{parameters}

Parameters

type
json or jsonp, must be specified.
tabId
A unique Tab id.

layoutTree (optional) : It expects a json object

widgetId
A unique id for the widget that is moved
orderNo
The position the widget wants to move to.
widgetGroup
The group that the widget wants to move to.

Save Widget

Note : This method only supports json and jsonp, which must be explicitly called with the parameter type.

url
widgetData/save{parameters}

Parameters

type
json or jsonp, must be specified.
tabId (string)
A unique tab id
orderNo (int)
The position in which the widget should appear.

isMinimized (bool)

title (string)

key (string)

isInEditMode (bool)

widgetGroup (string)

settings (json object)

widgetId (string)