/search

The /search endpoints are the main endpoints for searching and retrieving a list of documents that match a query and/or a set of conditions.

Table of Contents #

GET /search/geoevents #

Gets stories and dominant city matching a query.

NOTE: It is strongly recommended to use the /entities/geo endpoint as it gives better results. This endpoint is mainly kept for backwards compatibility.

If no coordinates are given to the api call it will search globally. Otherwise it is possible to specify a certain area with the lat/long parameters.

Request

GET /search/geoevents{parameters}

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.

Response

Returns an item array with the most relevant stories matching the search and the dominant city for each story.

Example:

{
    "Items": [
        {
            "Term": {
                "EntityReference": "arak-11_91544",
                "Id": "11_91544",
                "Description": "Arak",
                "Type": "City",
                "LocalizedType": "City",
                "LastUpdated": "0001-01-01T00:00:00"
            },
            "Story": {
                "FirstReported": "2013-11-15T09:48:00Z",
                "NoDocuments": 1,
                "ClusterId": "16_2267242284846153825",
                "PublicationDate": "2013-11-15T09:48:00Z",
                "CreatedDate": "2013-11-15T13:09:38Z",
                "Publisher": "Bloomberg",
                "Language": "en",
                "SourceUrl": "http://www.bloomberg.com/news/2013-11-15/iran-mutes-french-clamor-by-slowing-reactor-freezing-expansion.html",
                "IndexOrder": 126316310,
                "ContributingUserId": 0,
                "SilobreakerUrl": "https://api.silobreaker.com/5_2267244224023887912",
                "Id": "5_2267244224023887912",
                "Description": "Iran Mutes French Clamor by Slowing Reactor, Freezing Expansion",
                "Type": "Article",
                "LocalizedType": "Article",
                "Extras": { },
                "LastUpdated": "2013-11-15T09:48:00Z"
            },
            "Latitude": 34.08000183105469,
            "Longitude": 49.70000076293945,
            "Weight": 1,
            "LastUpdated": "0001-01-01T00:00:00"
        }
    ],
    "LastUpdated": "0001-01-01T00:00:00"
}

GET /search/topstories #

Gets top stories relevant to the query.

A Top Story is a cluster of documents that are all closely related and concerns the same news event.

Request

GET /search/topstories/{query}

Parameters

q : The query string to search for.

noStories : Number of stories to return. Default is 5.

storyType : The cluster type. At the moment only default exists.

storySelector (optional) : Choose what type of algorithm should be used to order the stories.

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.

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

Response

The total number of stories retrieved, their description, and a number of stories. Each story contains a number of documents, and are represented by an example article from the cluster, which is also provided.

Example:

{
    "TotalCount": 1,
    "Description": "",
    "Items": [
        {
            "FirstReported": "2013-11-14T10:40:00Z",
            "NoDocuments": 65,
            "ClusterId": "16_2267242085130174496",
            "PublicationDate": "2013-11-15T10:13:00Z",
            "CreatedDate": "2013-11-15T13:46:54Z",
            "Publisher": "CHINAdaily",
            "Language": "en",
            "SourceUrl": "http://www.chinadaily.com.cn/xinhua/2013-11-15/content_10596633.html",
            "IndexOrder": 126321457,
            "ContributingUserId": 0,
            "SilobreakerUrl": "https://api.silobreaker.com/5_2267244255162400779",
            "Id": "5_2267244255162400779",
            "Description": "Philippines defends accuracy of death toll from typhoon Haiyan",
            "Type": "Article",
            "LocalizedType": "Article",
            "LastUpdated": "2013-11-15T10:13:00Z"
        }
    ],
    "LastUpdated": "0001-01-01T00:00:00"
}

GET /search/social #

Searches selected social media providers for matches to the given query.

Request

GET /search/social
GET /search/social/{query}
GET /search/social/{query}/{providers}

Parameters

q : The query string to search for.

providers (optional) : Comma-separated list of providers to search. Supported providers are Twitter and Facebook.

languages (optional) : set a language iso code

Response

Example: For the query https://api.silobreaker.com/search/social/Silobreaker?type=json, we receive

{

    "Statuses": [ ],
    "Items": [
        {
            "Authors": [
                {
                    "Name": "Cate Farrall",
                    "Uri": "https://twitter.com/CateF",
                    "UserId": "CateF",
                    "ProfileImageUri": "https://pbs.twimg.com/profile_images/344513261572128225/e267a502ca089eaf8dfe547129045a4c_normal.jpeg"
                }
            ],
            "Id": "401282441928650752",
            "Provider": "Twitter",
            "Links": [
                {
                    "Href": "https://twitter.com/CateF/status/401282441928650752",
                    "Rel": "alternate",
                    "Type": "text/html"
                }
            ],
            "Published": "2013-11-15T09:36:04Z",
            "Updated": "2013-11-15T09:36:04Z",
            "Source": {
                "Link": "http://www.twitter.com",
                "Title": "Twitter"
            },
            "Contents": [
                {
                    "Type": "html",
                    "Lang": "en",
                    "Text": "The need to know what your competitors in business... - Silobreaker <a href=\"http://t.co/cpQJvgawFW\" target=\"_blank\" >news.silobreaker.com/the-need-to-kn…</a>"
                }
            ],
            "LastUpdated": "0001-01-01T00:00:00"
        }
    ],
    "LastUpdated": "0001-01-01T00:00:00"

}

GET /search/documents #

Retrieves documents that match the query.

Request

GET /search/documents 
GET /search/documents/{query}
GET /search/documents/{query}/{types}

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):

Response

Example: To return the single most relevant blog mentioning "United Nations", use the request /search/documents/United Nations?types=blog&pageSize=5&sortBy=relevance&type=json, which returns

{
    "TotalCount": 15585,
    "Description": "United Nations",
    "Items": [
        {
            "FirstReported": "2013-11-15T08:31:00Z",
            "NoDocuments": 1,
            "PublicationDate": "2013-11-15T08:31:00Z",
            "CreatedDate": "2013-11-15T11:13:36Z",
            "Publisher": "Direktbroker.de",
            "Language": "de",
            "SourceUrl": "http://www.direktbroker.de/news/united-nations-says-4-460-have-been-recorded-killed-by-32931612",
            "IndexOrder": 126300893,
            "ContributingUserId": 0,
            "SilobreakerUrl": "https://api.silobreaker.com/5_2267244137050800146",
            "Id": "5_2267244137050800146",
            "Description": "United Nations says 4,460 have been recorded",
            "Type": "Article",
            "LocalizedType": "Article",
            "LastUpdated": "2013-11-15T08:31:00Z"
        }
    ],
    "LastUpdated": "0001-01-01T00:00:00"
}

GET /search/quotes #

Gets quotes matching a document query.

The response will be in the format of QuoteData which has the following fields:

Request

GET /search/quotes    

Parameters

q : A query which will be used to search for quotes.

itemRef : Use this parameter to ensure that a person is mentioned in the quote.

allowQuotesFromSameDocument : A boolean flag that can be used if quotes from same documents should be included. It defaults to false.

length : The length of the surrounding text around the quote.

PreLength : The minimum length of the text before the quote

PostLength : The minimum length of the text after the quote

Response

Example: To return the quotes about Justin Beiber", use the request /search/quotes?q=Justin Bieber [Person]&type=json, which returns

{
   Items: [
      {
         Quote: "It appears this stems from a domestic issue with a break-up in the family, from what our witness has told us,",
         PreText: "",
         PostText: "Assistant Chief Deputy Constable Mark Herman of the Harris County Precinct 4 Constable's Office told reporters. He did not explain further",
         SourceDocument: {
            PublicationDate: "2014-07-10T05:49:00Z",
            CreatedDate: "2014-07-10T07:50:29Z",
            Publisher: "Bray People",
            Language: "en",
            SourceUrl: "http://www.independent.ie/world-news/father-kills-six-in-texas-shooting-30420933.html",
            IndexOrder: 160437423,
            ContributingUserId: 0,
            SilobreakerUrl: "https://my.localsb.net/5_2268077380033576972",
            Id: "5_2268077380033576972",
            Description: "03:33Father kills six in Texas shooting",
            Type: "Article",
            LocalizedType: "Article",
            LastUpdated: "0001-01-01T00:00:00"
         },
         LastUpdated: "0001-01-01T00:00:00"
      },
      {
         Quote: "Justin ist froh, die Sache geklärt zu haben und nun hinter sich lassen zu können. Er wird sich jetzt auf die Zukunft, auf seine Karriere und seine Musik konzentrieren.",
         PreText: "...In einer schriftlichen Stellungnahme nach der Anhörung vor Gericht, teilte ein Sprecher des Popstars mit:",
         PostText: "Der betroffene Nachbar hatte nach der Eierattacke auf sein Haus Rechnungen für Renovierungen in Höhe von 20.000 Dollar (14...",
         SourceDocument: {
            PublicationDate: "2014-07-10T06:09:00Z",
            CreatedDate: "2014-07-10T08:18:58Z",
            Publisher: "Klamm.de",
            Language: "de",
            SourceUrl: "http://www.klamm.de/news/justin-bieber-2-jahre-bewaehrung-und-aggressionstherapie-36NBS2BS779354.html",
            IndexOrder: 160440466,
            ContributingUserId: 0,
            SilobreakerUrl: "https://my.localsb.net/5_2268077405803380825",
            Id: "5_2268077405803380825",
            Description: "Justin Bieber: 2 Jahre Bewährung und Aggressionstherapie",
            Type: "Article",
            LocalizedType: "Article",
            LastUpdated: "0001-01-01T00:00:00"
         },
         LastUpdated: "0001-01-01T00:00:00"
      }],
   LastUpdated: "0001-01-01T00:00:00"
}

GET /search/documents/property #

Gets documents that has a property with a specific value.

Only properties with text or numeric values are supported.

Request

GET /search/documents/property

Parameters

name : The name of the property to search for

value : The value of the property

Response

Example: To return any documents with the property FileType=pdf request /search/documents/property?name=FileType&value=pdf&type=json, which returns

{
    "Items": [
        {
            "FirstReported": "2008-01-29T16:32:00Z",
            "NoDocuments": 1,
            "PublicationDate": "2008-01-29T16:32:00Z",
            "CreatedDate": "2008-01-29T18:08:00Z",
            "Publisher": "LocalFile",
            "Language": "en",
            "IndexOrder": 54256,
            "ContributingUserId": 0,
            "SilobreakerUrl": "https://my.localsb.net/5_2260942287229943811",
            "Id": "5_2260942287229943811",
            "Description": "EarthmonitoringCinderellascience_Nature.pdf",
            "Type": "Local File",
            "LocalizedType": "Local File",
            "LastUpdated": "2008-01-29T16:32:00Z"
        }
    ]
}

GET /search/provider #

Searches for a document that has a specific provider--reference pair.

Request

GET /search/documents/provider{parameters}

Parameters

provider : The provider part of the provider--reference pair

reference : The reference part of the provider--reference pair

Response

Example: To get a document with provider=Moreover and reference=19234403719 the request /search/documents/provider?provider=moreover&reference=19234403719&type=json will return

{
   "Items": [
      {
         "FirstReported": "2014-10-13T11:11:00Z",
         "NoDocuments": 1,
         "PublicationDate": "2014-10-13T11:11:00Z",
         "CreatedDate": "2014-10-13T11:42:36Z",
         "Publisher": "Noodls",
         "Language": "en",
         "SourceUrl": "http://ct.moreover.com/?a=19234403719&p=12y&v=1&x=exyPgTxn6MxVHed4wBQ-iQ",
         "IndexOrder": 173454895,
         "ContributingUserId": 0,
         "SilobreakerUrl": "https://my.localsb.net/5_2268295454850547866",
         "Id": "5_2268295454850547866",
         "Description": "Pitt Researchers Receive $1.25 Million from Defense Department to Make Whole-Eye Transplantation a Reality »",
         "Type": "Article",
         "LocalizedType": "Article",
         "LastUpdated": "2014-10-13T11:11:00Z"
      }
   ]
}

Documentation generated by mdoc.