/entities

Table of Contents #

GET /entities #

Searches for entities matching a query.

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

Request

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

Parameters

q : The query to search for.

types : Comma separated list of entity types that should be returned. See full list of entity types for supported types.

Not specifying any entity types will return all of them.

pageSize : Number of entities to return. Default is 20.

pageNumber : Window the result to a specific page. First page is 0.

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

sortBy : How the result should be sorted. Default is relevance. Possible values are:

Response

Example: To return the 5 most relevant entities having Obama in its name, use entities/Obama?pageSize=2&type=json which will give a result like

{
      "TotalCount": 89,
      "Description": "Obama",
      "Items": [
         {
            "EntityReference": "michelle-obama-11_8081593",
            "Id": "11_8081593",
            "Description": "Michelle Obama",
            "Type": "Person",
            "LocalizedType": "Person",
            "LastUpdated": "0001-01-01T00:00:00"
         },
         {
            "EntityReference": "barack-obama-11_240886",
            "Id": "11_240886",
            "Description": "Barack Obama",
            "Type": "Person",
            "LocalizedType": "Person",
            "LastUpdated": "0001-01-01T00:00:00"
         }
      ],
      "LastUpdated": "0001-01-01T00:00:00"
}

GET /entities/heat #

Gets the heat for a set of entities.

Heat calculates the heat, a measure of how much more than usual an entity is mentioned, for a given entity.

Request

entities/heat{parameters}

Parameters

q (string) : The query to filter on. (This only works if you have access to InMem and forceDb flag is set to false)

forceDb (bool) : Defaults to false, forces the backend mechanism to use SQL routing.

tq (string) : A query that will get the terms that are used for the heat calculation. This query should follow the same syntax as the base entities endpoint.

projectref (string) : Expects a projectRef which is used to get the items that are used in the heat calculation.

itemrefs (list of strings) : Expects a comma separated list of itemrefs which is used as the items for the heat calculation. When you have the itemref this is faster and scales better than using the term query (tq) parameter.

sortBy (string) : Choose what column to sort by possible entries are: name, type, heat1d (default), heat7d, vol1d, vol7d, vol30d

sortDirection (string) : Defaults to desc

Response

Example: The query https://api.silobreaker.com/entities/heat?tq=person:barack+obama&type=json returns

{
      "TotalCount": 1,
      "Description": "*",
      "Items": [
         {
            "EntityReference": "barack-obama-11_240886",
            "Id": "11_240886",
            "Description": "Barack Obama",
            "Type": "Person",
            "LocalizedType": "Person",
            "Extras": {
                  "DocVolume-1": {
                     "Volume": 508,
                     "LastUpdated": "0001-01-01T00:00:00"
                  },
                  "DocVolume-7": {
                     "Volume": 5353,
                     "LastUpdated": "0001-01-01T00:00:00"
                  },
                  "DocVolume-30": {
                     "Volume": 25098,
                     "LastUpdated": "0001-01-01T00:00:00"
                  },
                  "Heat-1/30": {
                     "Heat": 0.6076886341929322,
                     "LastUpdated": "0001-01-01T00:00:00"
                  },
                  "Heat-7/30": {
                     "Heat": 0.9141765588756992,
                     "LastUpdated": "0001-01-01T00:00:00"
                  }
            },
            "LastUpdated": "0001-01-01T00:00:00"
         }
      ],
      "LastUpdated": "0001-01-01T00:00:00",
      "Source": "InMem"
}

GET /entities/evidence #

Gets an evidence snippet from recent news.

An evidence snippet is a short piece of text with the supplied entity in context in an article.

Request

entities/evidence

url : /evidence : /evidence/{entityReference}

Parameters

entityReference (required) : A reference to the entity, of the format 11_NUMBER. An entity reference must be given.

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

Response

The query entities/evidence/11_86436780?type=json will return

{
      "ItemSet": [
         {
            "EntityReference": "quintus-tullius-cicero-11_86436780",
            "Id": "11_86436780",
            "Description": "Quintus Tullius Cicero",
            "Type": "Person",
            "LocalizedType": "Person",
            "LastUpdated": "0001-01-01T00:00:00"
         }
      ],
      "Extras": {
         "RelatedDocuments": {
            "TotalCount": 0,
            "Items": [ ],
            "LastUpdated": "0001-01-01T00:00:00"
         }
      },
      "LastUpdated": "0001-01-01T00:00:00"
}

GET /entities/property #

Serches entity metadata for entites by property name (dimension) and value.

Request

   GET /entities/property{parameters}

Parameters

name : The name of the property to lookup

value : The specific value that should match the property.

Response

Example: The request https://api.silobreaker.com/entities/property?name=Title&value=US%20President&type=json gives the following response:

{
   Items: [
      {
      EntityReference: "barack-obama-11_240886",
      Id: "11_240886",
      Description: "Barack Obama",
      Type: "Person",
      LocalizedType: "Person"
      }
   ]
}

GET /entities/geo #

Extracts entities that has geographical coordinates (such as cities and sites) and that are related to a query.

Request

GET /entities/geo

Parameters

q : The query string to search for.

maxLat : (Optional) The maximum latitude of the entities

minLat : (Optional) The minimum latitude of the entities

maxLong : (Optional) The maximum longitude of the entities

minLong : (Optional) The maximum longitude of the entities

sortBy : (Optional) Sort the entites either by "relevance" (default) or by "count". This also affects how the size is calculated (see more below).

size : (Optional) The maximum number of entites to return. Defaults to 10 if omitted.

Response

Example return value:

{
   "Items": [
      {
         "Item": {
            "Id": "11_94512",
            "Description": "Baghdad",
            "Type": "City"
         },
         "Latitude": 33.33000183105469,
         "Longitude": 44.439998626708984,
         "Size": 45.529417898491374
      }
   ]
}

Size is calculated as in relation to the query. It is either the relevance or the number of occurences depending on the sortBy parameter.

GET /entities/refresh #

Refreshes a list of entities.

Request

GET /entities/refresh/{parameters}

Parameters

termids : A comma separated list of termids.

Response

Example: The API request entities/refresh?termids=237262,237360,411011&type=json will produce

{
    TotalCount: 3,
    Description: "Terms refreshed",
    Items: [
        {
            EntityReference: "hilary-duff-11_237262",
            Id: "11_237262",
            Description: "Hilary Duff",
            Type: "Person",
            LocalizedType: "Person",
            LastUpdated: "0001-01-01T00:00:00"
        },
        {
            EntityReference: "hillary-clinton-11_237360",
            Id: "11_237360",
            Description: "Hillary Clinton",
            Type: "Person",
            LocalizedType: "Person",
            LastUpdated: "0001-01-01T00:00:00"
        },
        {
            EntityReference: "white-house-11_411011",
            Id: "11_411011",
            Description: "White House",
            Type: "Keyphrase",
            LocalizedType: "Keyphrase",
            LastUpdated: "0001-01-01T00:00:00"
        }
    ],
    LastUpdated: "0001-01-01T00:00:00"
}

Documentation generated by mdoc.