REST API Reference Specification

Current Version = v1

Table of Content

1 Introduction

2 URIs and Response Types

3 Versioning

4 Resources

5 Core Concepts

6 Example Scenarios

7 Code Samples

8 Feedback and Troubleshooting

9 Known Issues

Introduction

The Evri API gives you programmatic access to Evri’s rich mapping of the entity web, or the web of people, places and things connected to one another via language itself. The Evri API exposes portions of Evri’s deep NLP based technology as well as Evri’s extensive knowledgebase of information about entities. For more on Evri’s technology, please see the tech talk pages on the Evri blog. Most functionality seen on www.evri.com as well as that exposed via Evri widgets is based on the Evri API. The Evri API is a REST based service whose results are returned in either XML or JSON and can be easily processed in most programming languages including, but not limited to: JavaScript, Python, Ruby, Perl, ActionScript, Java, C#, C, C++ and more. Among other things, the Evri API enables you to find:

Here are some example questions which the Evri API can help answer:

Note: Before proceeding, please review our terms of service agreement. By accessing or using the Evri API, you are agreeing to be bound by that agreement. If you wish to reproduce or redistribute this documentation in whole or in part, you must retain this notice and a link to the agreement.

Note:The Evri API is currently in an early preview stage. Only a small portion of our extensive knowledgebase and NLP based text analysis and search infrastructure is currently exposed. We are committed to exposing more and more of our powerful entity web platform over time; this preview release is the first step. In addition, we are currently not requiring application ids or a sign up. We will, however, in the near future require Evri API requests to include an application id which will require a sign up. We will provide a time window for which you can transition to using an application id for your application. We welcome any API feedback including ways to make the Evri API easier to use. Please use the developer forum to tell us about your successes and challenges. We will respond to your questions as promptly as we can.

Note:Usage of the Evri API is subject to a maximum of 10,000 requests per day, and we require that you make no more than 1 query per second. If you would like to increase this limit, please contact us at api@evri.com.

URIs and Response Types

Every resource in the Evri system is addressable by a URI. URIs are used in returned data to refer to the resource; you will be directed to use these URIs as request parameters or as part of the request path when using the Evri API. Here are a few example URIs:

URIs allow you to access resources via HTTP. Resources have two response types: XML, and JSON.

You can specify your desired response type by appending “.xml”, or “.json” to the end of a resource name. For example, this URI:

http://api.evri.com/v1/person/barack-obama-0x16f69.xml?appId=evri.com-restdoc

returns results in XML format. While this URI:

http://api.evri.com/v1/person/barack-obama-0x16f69.json?appId=evri.com-restdoc

returns results in JSON.

If you do not specify the response type, results will be returned in XML format.

Versioning

A specific version of an Evri API result is obtained by appending the version number to the request right after http://api.evri.com. For example, to get results in version v1 format, specify:

http://api.evri.com/v1/zeitgeist/entities/person/all.xml?appId=evri.com-restdoc

A version is required; this is to assist us in creating a new version of the Evri API while maintaining some degree of backward compatibility.

Note: during the preview stage of the Evri API, we are not promising backward compatibility. This means we may release a new version of the Evri API and break a prior version; you will need to upgrade your application in this event. Once our API preview stage is completed, we will be offering a limited time period of backward compatibility for a prior release to enable you sufficient time to upgrade from a deprecated resource. Resource deprecation will be indicated in the result message field.

Resources

1 Get zeitgeist information

2 Get information about an entity

3 Get relations about an entity

4 Get entities and factual information

5 Get entity network about some text

6 Get media about an entity

7 Get media about an entity - alternate form

8 Get a related entity network about an entity

9 Get sentiment information

10 Get quotations

Get zeitgeist information

Description

Returns a list of entities or facets ranked by popularity. Popularity is determined by multiple factors including but not limited to www.evri.com usage activity and mentions on the web, news and blogs.

Usage

[zeitgeist/[elementType]?[inputParameters]

where

elementType is 1 of: entities, facets

and for elementType entities:

the usage pattern is

[zeitgeist/entities/[entityType]/[zeitgeistType]?[inputParameters]

where

and applicable inputParameters include: resultsPerPage, appId and callback.

and for elementType facets:

the usage pattern is

[zeitgeist/facets/[FACET]?[inputParameters]

where

and applicable inputParameters include: startId, resultsPerPage, appId and callback.

Note: paging in this API resource variant deviates from the API standard. In this resource variant startId is not a numerical value, but rather, the next or prev attribute shown in the entitiesByFacet node of the result response. This inconsistency will be addressed in a future release of the API.

Note: the totalEntityCount attribute of the entitiesByFacet node of the result response is a maximum value. There are cases where less than this number will be returned.

Examples

1 Get popular people - http://api.evri.com/v1/zeitgeist/entities/person/popular?appId=evri.com-restdoc

2 Get popular people whose popularity is rising - http://api.evri.com/v1/zeitgeist/entities/person/rising?appId=evri.com-restdoc

3 Get popular organizations - http://api.evri.com/v1/zeitgeist/entities/organization/popular?appId=evri.com-restdoc

4 Get popular organizations using JSONP callback - http://api.evri.com/v1/zeitgeist/entities/organization/popular.json?callback=foo&appId=evri.com-restdoc

5 Get facets ranked by popularity of occurrence - http://api.evri.com/v1/zeitgeist/facets?appId=evri.com-restdoc

6 Get entities ranked by popularity for a particular facet - http://api.evri.com/v1/zeitgeist/facets/band?appId=evri.com-restdoc

7 Page through entities ranked by popularity for a particular facet - Start by calling http://api.evri.com/v1/zeitgeist/facets/band?appId=evri.com-restdoc. Take the next attribute of the entitiesByFacet node of the result response and set it as the startId inputParameter. At the time of writing this document, the next attribute was /organization/black-eyed-peas-0x12a50|16914|n so to get the next page of results the appropriate call was http://api.evri.com/v1/zeitgeist/facets/band?startId=/organization/black-eyed-peas-0x12a50|16914|n&appId=evri.com-restdoc.

Get information about an entity

Description

Returns structured information about an entity. Returned information includes:

Usage

[entityURI]?[inputParameters]

where

applicable inputParameters include: callback.

Examples

1 Get information about Barack Obama - http://api.evri.com/v1/person/barack-obama-0x16f69?appId=evri.com-restdoc

2 Get information about Canada - http://api.evri.com/v1/location/canada-0x3ad37?appId=evri.com-restdoc

Get relations about an entity

Description

Returns relations for an entity. Returned relations can be a facet, query template, verb, or concept. In addition, a relation graph of the most relevant entity relations to the specified entity is returned.

Usage

[entityURI]/relations/[relationType]/[relationName]/[entityURI2]?graphRelationsCount=GRAPH_COUNT&[inputParameters]

where

relationType can be one of: relatedTo, facet, qt, verb or concept

and

for facet:

for qt:

for verb:

and GRAPH_COUNT is the maximum number of relations to include in a returned graph

and applicable inputParameters include: callback.

Examples

1 Returns relations for an entity and a graph depicting the top relations

2 Returns only a graph depicting the top relations

3 Returns related politicians to the specified entity

4 Returns relations involving the specified politician to the specified entity

5 Returns relations involving the specified entity and the specified query template

6 Returns relations involving the specified entity, the specified query template, and the second specified entity

7 Returns all relations involving the specified entity and the specified verb

8 Returns all relations involving the specified entity, the specified verb, and the second specified entity

Get entities and factual information

Description

Returns entities present in the Evri knowledgebase based on input criterion and ranks the results by popularity. Specify an entity name to find all entities in the Evri entity store with that name. Specify an entity type or facet to retrieve top ranked entities belonging to that type or facet. Constrain results by entity property including the ability to search inside an entity property, such as description paragraphs. Combine any of the above requests in various boolean forms to achieve significant expressiveness. Finally, specify a prefix to an entity name to build auto-suggest like functionality by finding all entities whose name starts with the prefix.

Usage

entities/[find]?[searchArgs]&[inputParameters]

where applicable inputParameters include: facet, type, startId, resultsPerPage, appId and callback.

and in requests of the form:

entities/find?prefix=PREFIX&[inputParameters]

PREFIX is the entity name prefix used for an auto suggest style search

and where for requests of the form:

entities?[searchArgs]&[inputParameters]

searchArgs has the following parameters or arguments

1 name=NAME

where NAME is the name of the entity you wish to find and

2 typeArgs includes type=TYPE

indicates type constraints about the entities you wish to find and

3 facetArgs includes facet=FACET

indicates facet constraints about the entities you wish to find and

4 propertyArgs includes property=PROPERTY

indicates property presence constraints about the entities you wish to find and

Note: To determine which properties are available, use the Get information about an entity resource for a sample return entity.

5 propertyValueArgs including propertyValue=PROPERTY_VALUE

indicates propertyValue constraints about the entities you wish to find and

Note: To determine which properties are available, use the Get information about an entity resource for a sample return entity.

Examples

1 Find all entities named Bush: http://api.evri.com/v1/entities?name=Bush&appId=evri.com-restdoc

2 Find the top entities whose name starts with the letters Ob: http://api.evri.com/v1/entities/find?prefix=Ob&appId=evri.com-restdoc

3 Find all entities who have a death date: http://api.evri.com/v1/entities?property=death_date&appId=evri.com-restdoc

4 Find all people that are lawyers but not politicians: http://api.evri.com/v1/entities?facet=lawyer&facet=-politician&type=person&appId=evri.com-restdoc

5 Find all albums recorded by U2: http://api.evri.com/v1/entities?facet=album&propertyValue=recording_artist:U2&appId=evri.com-restdoc

6 Find the top 50 songs or albums recorded by Nirvana: http://api.evri.com/v1/entities?facet=song,album&propertyValue=recording_artist:nirvana&resultsPerPage=50&appId=evri.com-restdoc

7 Find the 11th to 20th most popular albums recorded by either Eartha Kitt or U2: http://api.evri.com/v1/entities…

8 Find all people whose wikipedia paragraph description contains the term: cocaine dealer: http://api.evri.com/v1/entities…

9 Find all actors or musicians whose wikipedia paragraph description mentions a drug: http://api.evri.com/v1/entities…

10 Find all films directed in the 1990s by Oliver Stone: http://api.evri.com/v1/entities…

11 Find all people that are actors and politicians: http://api.evri.com/v1/entities?facet=actor&facet=politician&appId=evri.com-restdoc

12 Find all quarterbacks that wore a number 12 jersey: http://api.evri.com/v1/entities…

13 Find the top ranked heavy metal or grunge songs: http://api.evri.com/v1/entities…

14 Find the top ranked bands classified as both heavy metal and grunge: http://api.evri.com/v1/entities…

Get entity network about some text

Description

Returns an entity network depicting relations between entities based on a blob of text. The returned entity network includes all entities present in the text with disambiguation applied. Entity disambiguation includes, for example, differentiating between Will Smith the actor, and Will Smith the football player.

Note: If submitted text represents an article or post, the submitted text should include the article title, two line breaks, followed by the article. Ideally, all formatting such as HTML tags should be stripped from the submitted text for optimal results.

Usage

media/entities?uri=URI&[textParameters]&[inputParameters]

where

URI = URI of the article. Needed for optimal performance and efficacy.

and textParameters can be:

1 text=TEXT where TEXT is the complete text of the article including the title in simple ASCII format. Note: Submitted text should include the title, two line breaks, then the article body. All markup should be stripped from the text. Case should be preserved in the text.

2 html=HTML where HTML is the complete text of the article in HTML format. Note: HTML fragments are okay; it is best to include a fragment with no unclosed HTML tag. In addition, non essential non-natural language markup may be removed for better performance; for example, stripping tags related to advertisements is a good idea. In general, the simpler the HTML, the better.

and

applicable inputParameters include: callback.

Note: Include the text parameter on the first attempt to make this call. After the first submission, the text parameter only needs to be submitted if the call without it fails. This call sequencing is needed for optimal performance and to save on bandwidth.

Note: the system performs best on natural language text; this means accuracy will be lower if natural language sentences are not included, or if navigational information, or raw tables of information are dumped into the text.

Example

1 Returns a network of entity information related to text.

http://api.evri.com/v1/media/entities?uri=http://www.mysite.com&text=Seattle%20is%20nice%20in%20the%20December%20months%20when%20Pearl%20Jam%20and%20Alice%20in%20Chains%20are%20rocking%20out.&appId=evri.com-restdoc

2 Returns a network of entity information related to text where submitted text has HTML markup.

http://api.evri.com/v1/media/entities…

3 Returns a network of entity information related to text previously submitted for the same URI.

http://api.evri.com/v1/media/entities?uri=http://www.mysite.com&appId=evri.com-restdoc

Get media about an entity

Description

Returns related media including articles, images and video for an entity. Returned media types can be constrained; for example, results containing only images, or results containing images and video can be returned. Returned media type default is articles. In the event the specified entity has the same as other entities, only media corresponding to the specified entity is returned.

Usage

[entityURI]/media/related?[constraint]&includeTopEntities=BOOLEAN_VALUE&[inputParameters]

where

constraint is optional and can be either: entityArgs, or a queryToken

where

1 entityArgs are of the form: entityURI=entityURI1&entityURI=entityURI2, …

2 queryToken is returned from a /media/entities call.

and

1 includeTopEntities=true indicates top entities present in returned articles will be included in the response.

2 includeTopEntities is either not specified or set equal to false indicates top entities present in returned articles will not be included in the response.

and

applicable inputParameters include: queryToken, articleSnippetLength, includeMatchedLocations, type, startId, resultsPerPage, includeDomains, excludeDomains, includeDates, appId and callback.

Examples

1 Get related articles about an entity

http://api.evri.com/v1/person/robert-mugabe-0x2446e/media/related?appId=evri.com-restdoc

2 Get related articles about an entity constrained to a particular set of domains

http://api.evri.com/v1/person/robert-mugabe-0x2446e/media/related?includeDomains=wikipedia.org,infoplease.com&appId=evri.com-restdoc

3 Get related articles about an entity constrained to a particular set of dates

http://api.evri.com/v1/person/robert-mugabe-0x2446e/media/related?includeDates=20090201,20090202,20090203&appId=evri.com-restdoc

4 Get related articles, images and videos about an entity

http://api.evri.com/v1/person/robert-mugabe-0x2446e/media/related?type=article,video,image&appId=evri.com-restdoc

5 Get the second page of related videos about an entity

http://api.evri.com/v1/person/robert-mugabe-0x2446e/media/related?type=video&startId=10&resultsPerPage=10&appId=evri.com-restdoc

6 Get related articles about an entity and another entity

http://api.evri.com/v1/person/barack-obama-0x16f69/media/related?entityURI=person/hillary-clinton&type=article&appId=evri.com-restdoc

7 Get related articles about an entity in the context of a trigger article (with a queryToken constraint applied)

http://api.evri.com/v1/person/barack-obama-0x16f69/media/related?queryToken=vVHLbsIw…

Get media about an entity - alternate form

Description

Returns related media including articles, images and video for an entity. Alternate form of Get media about an entity.

Usage

media/related?entityURI=ENTITY_URI&includeTopEntities=BOOLEAN_VALUE&[inputParameters]

where

ENTITY_URI is called as an HRef in XML; for example: person/robert-mugabe-0x2446e

and

1 includeTopEntities=true indicates top entities present in returned articles will be included in the response.

2 includeTopEntities is either not specified or set equal to false indicates top entities present in returned articles will not be included in the response.

and

applicable inputParameters include: queryToken, articleSnippetLength, type, includeMatchedLocations, startId, resultsPerPage, includeDomains, excludeDomains, includeDates, appId and callback.

Examples

1 Get articles, videos and images about an entity

http://api.evri.com/v1/media/related?entityURI=person/robert-mugabe-0x2446e&appId=evri.com-restdoc

2 Get articles about an entity

http://api.evri.com/v1/media/related?entityURI=person/robert-mugabe-0x2446e&type=article&appId=evri.com-restdoc

3 Get the second page of related videos about an entity

http://api.evri.com/v1/media/related?entityURI=person/robert-mugabe-0x2446e&type=video&startId=10&resultsPerPage=10&appId=evri.com-restdoc

Get a related entity network about an entity

Description

Returns an entity network depicting relations between entities based on a queryToken which represents contextual information about an entity, entity pair or article.

Usage

[entityURI]/related/entities?uri=URI&queryToken=QUERY_TOKEN&[inputParameters]

where

1 URI is the URI of the trigger article

2 QUERY_TOKEN is a string representing contextual information about an entity, entity pair, or article.

and

applicable inputParameters include: callback.

Examples

1 Returns a network of entity information related to an entity

http://api.evri.com/v1/person/barack-obama-0x8c8/related/entities?uri=http://www.mysite.com&queryToken=vVHLbsIwEAxOP…

Get sentiment information

Description

Returns sentiment by someone or something about someone or something. Typical usage includes an initial request for sentiment summary information; summary information includes the percentage of positive and negative sentiment expressed by an entity or facet, or about an entity or facet on the web; summary information may include specific entities which are critics, praisers, recipients of criticism, or recipients of praise of an entity or facet. Once summary information has been obtained, typical use involves more refined requests to return sentiment involving specific entities and/or facets; returned sentiment includes a reference to an article (e.g. news article, blog post or web page) including a summary sentence expressing positive or negative sentiment.

Usage

sentiment/[summary]/[about]?sentimentType=SENTIMENT_TYPE&includeSummaryDetails=BOOLEAN_VALUE&sentimentSource=SENTIMENT_SOURCE&[inputParameters]

where

applicable inputParameters include: facet, entityURI, includeDomains, excludeDomains, includeDates, includeMatchedLocations, startId, resultsPerPage, sort, appId and callback.

and

1 sentimentSource parameter indicates the source of the sentiment (i.e. entity, or facet) is specified. If the source is an entity, an entityURI is specified. If the source is a facet, then a facet is specified.

2 entityURI parameter presence indicates the subject of the sentiment is specified.

3 facet parameter presence indicates the subject of the sentiment is specified. Note: facets must use an underscore (i.e. ‘_’) instead of whitespace.

4 SENTIMENT_TYPE is a type of sentiment which can be either: positive, negative

5 includeSummaryDetails=true indicates critics, praisers, recipients of criticism, or recipients of praise of an entity or facet should be returned. If the sentimentSource is specified, recipients of criticism and recipients of praise are returned. If instead, the entityURI or facet is specified, critics and praisers of the entity or facet are returned.

Examples

1 Simple sentiment summary by the entity NATO. Returns percentage of positive and negative sentiment expressions by NATO.

http://api.evri.com/v1/sentiment/summary?sentimentSource=/organization/nato-0x308f6&appId=evri.com-restdoc

2 Simple sentiment summary about the entity Barack Obama. Returns percentage of positive and negative sentiment expressed about Barack Obama. Results are sorted by date.

http://api.evri.com/v1/sentiment/summary/about?entityURI=/person/barack-obama-0x16f69&sort=date&appId=evri.com-restdoc

3 Detailed sentiment summary about the entity NATO. Returns percentage of positive and negative sentiment expressed about NATO. Response also includes who (i.e. which entities) are expressing the positive and negative sentiment.

http://api.evri.com/v1/sentiment/summary/about?entityURI=/organization/nato-0x308f6&includeSummaryDetails=true&appId=evri.com-restdoc

4 Detailed sentiment summary by the entity Barack Obama. Returns percentage of positive and negative sentiments expressed by Barack Obama. Response also includes who (i.e. which entities) Mr. Obama is praising and criticizing.

http://api.evri.com/v1/sentiment/summary?sentimentSource=/person/barack-obama-0x16f69&includeSummaryDetails=true&appId=evri.com-restdoc

5 Detailed sentiment summary about the facet musician. Response includes the percentage of positive and negative sentiments expressed by anyone about musicians. The response also includes the specific entities praising and criticizing musicians.

http://api.evri.com/v1/sentiment/summary/about?facet=musician&includeSummaryDetails=true&appId=evri.com-restdoc

6 Most recent positive sentiment expressed by the entity Barack Obama about anything. Returns references to the specific articles and snippets where Barack Obama’s sentiments are expressed.

http://api.evri.com/v1/sentiment/about?sentimentSource=/person/barack-obama-0x16f69&sentimentType=positive&sort=date&appId=evri.com-restdoc

7 Most recent sentiment of anything about the entity Barack Obama. Returns references to the specific articles and snippets where sentiments about Barack Obama are expressed.

http://api.evri.com/v1/sentiment/about?entityURI=/person/barack-obama-0x16f69&sentimentType=positive&sort=date&appId=evri.com-restdoc

8 Negative sentiment of an entity about an entity. Specifically, negative sentiment expressed by Barack Obama about John McCain. Includes matched locations so Obama, McCain, and other key terms capturing the expressed sentiment can be bolded.

http://api.evri.com/v1/sentiment/about?entityURI=/person/john-mccain-0x2a2a7&sentimentSource=/person/barack-obama-0x16f69&sentimentType=negative&includeMatchedLocations=true&appId=evri.com-restdoc

9 Sentiment of an entity about any facet. Specifically, negative sentiments expressed by musicians about politicians.

http://api.evri.com/v1/sentiment/about?facet=politician&sentimentSource=musician&sentimentType=negative&appId=evri.com-restdoc

Get quotations

Description

Returns quotations made about a topic in the Evri corpus of news, blog and other web content. In addition, quotations made by a specific person may be returned.

Usage

quotations/[about]?[inputParameters]&speaker=SPEAKER&[inputParameters]

where

where SPEAKER is the URI, or href, of a person and applicable inputParameters include: facet, entityURI, includeDomains, excludeDomains, includeDates, includeMatchedLocations, and callback.

Examples

1 Quotations by a person about anything

http://api.evri.com/v1/quotations?speaker=/person/barack-obama-0x16f69&appId=evri.com-restdoc

2 Quotations by anyone about a specific entity

http://api.evri.com/v1/quotations/about?entityURI=/location/united-states-0x2ae4b&appId=evri.com-restdoc

3 Quotations by anyone about a facet

http://api.evri.com/v1/quotations/about?facet=politician&appId=evri.com-restdoc

4 Quotations by a person about an entity

http://api.evri.com/v1/quotations/about?entityURI=/person/george-w.-bush-0x1beeb&speaker=/person/barack-obama-0x16f69&appId=evri.com-restdoc

5 Quotations by a person about any entity of a facet

http://api.evri.com/v1/quotations/about?facet=politician&speaker=/person/barack-obama-0x16f69&appId=evri.com-restdoc

Input Parameters

The following parameters affect output results. See the usage section for each resource to assess applicability.

InputDescriptionValuesDefault
textText containing natural languageString of natural language text. For articles, title followed by 2 line breaks and the article body.None
queryTokenToken encapsulating trigger text context informationString returned as a part of an entity networkNone
articleSnippetLengthDesired length of snippets in characters1…N 195
includeMatchedLocations True if matched locations are desired1 of: 0, 1, false, trueFalse
entityURIA unique identifier to an entity.An entityURINone
facetA unique identifier to a facet.A valid entity facetNone
typeA unique identifier to a media type unless otherwise specified in a particular resource.1 or more of: article, video, imageArticle
startIdSets id for start index0…N0
resultsPerPageNumber of desired results per page0…N10
includeDomainsConstrain article results to specified domains1 or more domains comma separatedAll domains
excludeDomainsLimit articles to domains not included1 or more domains comma separatedNone
includeDatesLimit articles to dates listed1 to 3 dates comma separated in YYYYMMDD formatNone
callbackResponse applies JSONP format using callback of the specified nameAny stringNone
appIdUnique application identifierA string of the form \[hostname\]-\[app name\]None

Core Concepts

Concepts involved in Evri API usage are described below.

Entity

An entity is a noun or noun phrase. An entity has a type. An entity may have a facet. An entity may exist in an entity network.

Type

A type is a broad categorization of an entity. Every entity has a type. Here is a list of some types available in the Evri API:

Facet

A facet is a more specific categorization of an entity than type. A given entity can belong to only one type, but may have have multiple facets. For example, some facets for the type location are: City, Country, and Continent.

Relation

A relation describes how an entity or facet is related to another entity, facet, query template, or verb. A relation is rooted in the language present in a particular sentence or series of sentences. A relation can be thought of, from a linguistic vantage, as the subject of an action, the action (verb), and the object of an action. For example, in the sentence, “Barack Obama won the election.” Barack Obama > win > election forms a relation.

Query Template

Also known simply as a qt, a query template represents a verb form, or action, connecting the entities or facets forming a relation.

Verb

Denotes the part of speech of a sentence corresponding to an action.

Media

Media refers to an article, video, or image found on the web.

Entity Network

An entity network, or entity graph, is an encapsulated representation for a body of text depicting all of the entities in the body of text, all of the entity pairs in a body of text, and contextual information called query tokens required to receive subsequent media recommendations based on the body of text.

An entity network consists of

1 Query Tokens

2 Entities

3 Entity Pairs

An entity network is returned for the resources Get entity network about some text and Get a related entity network about an entity.

Relation Graph

A relation graph depicts the top relations for a given entity. The top relations are the relations deemed most relevant by the system to a specified entity at any point in time based on things being written about in the blogosphere, news, and on the web. A relation graph is returned for the resource Get relations about an entity. A relation graph can be used to visually depict the inter-relationships of multiple entities similar to those found in the http://www.evri.com entity detail pages; for example, the graph on the Barack Obama page was made using a relation graph.

Query Token

A returned graph contains query tokens which are submitted in subsequent API calls. A query token is a way of representing state information about an entity, entity pair, or article; this state information includes contextual cues required for subsequent calls to be accurate. For example, consider the following body of text:

Nirvana, Pearl Jam and Soundgarden are all vintage bands defining the grunge era. Nirvana’s lead singer often smashed guitars on stage.

A query token for Pearl Jam might involve key terms like: Nirvana, Soundgarden, grunge, bands. A query token for Nirvana, might combine information from the first and second sentence; it may involve similar key terms to those for Pearl Jam, but it might also involve the key term smashed guitars.

This means recommendations for Nirvana might be honed to involve smashed guitars since the surrounding article text triggering the recommendations specifically mentioned this issue. If query tokens are not used, recommendations are generically applied to an entity or entity pair with no trigger article based context.

Entity in a network

Any entity identified in submitted text is returned in an entity network. These entities have the following attributes:

1 name - The human readable entity name.

2 score A score depicting this entities relative importance in the submitted text.

3 uri - The entity identifier. See entity URI.

4 query token - State information required for subsequent queries involving this entity.

Entity URI

An entity is uniquely defined by its URI; if the URI ends in a hex value, such as person/barack-obama-0x16f69, then the entity exists in the Evri knowledgebase, and additional information can be obtained about the entity by using the Get information about an entity resource. If the entity URI does not end in a hex value, then the entity was not linked to an entity that exists in the Evri knowledgebase. In some cases not enough information is present in the submitted text to accurately link an entity to the Evri knowledgebase. For example, if the submitted text contains only the sentence: “Hillary said yes.” the system cannot determine which of the many entities named Hillary may be referred to.

Entity Pair

Entity pairs are returned in an entity network. Two entities are returned in a pair if the system believes the two entities have a relationship in the submitted text. As an example, consider a case where the following sentence was contained in submitted text: “World Trade Center developer Larry Silverstein commented in the news.” A returned entity network in this case might include an entity pair consisting of the World Trade Center and Larry Silverstein. Each entity pair contains a score which indicates the strength the relationship between two entities. Multiple entity pairs can be assembled to form a visual display depicting the inter-relationships of multiple entities similar to those found in the http://www.evri.com widgets. Finally, an entity pair queryToken is used to capture contextual state information which is used to obtain subsequent article, image, or video recommendations.

Example Scenarios

Exploration of a few example scenarios may help illustrate the interactive nature of the Evri API. For example, it is helpful to understand how to use the results of one API call as input to another API call in order to achieve a desired outcome.

1 Get entity information about popular entities

2 Get recommended articles based on text

3 Get recommended videos for an entity based on text

4 Get recommended articles for an entity

Get entity information about popular entities

Description

Consider a scenario where we wish to display a list of entities ranked by how popular each entity is. In addition to the name of the entity, assume we wish to display additional information about each entity like a description, some properties, etc.

Solution steps

1 Call Get zeitgeist information resource like http://api.evri.com/v1/zeitgeist/entities/person/popular to receive a list of handles to entities.

2 For each returned entity, take the href attribute and formulate a Get information about an entity resource request. For example, if the first entity looks like:

      < entity score="0.11503202" id="94057" href="/person/barack-obama-0x16f69" > ... < /entity >

take the href attribute and formulate the Get information about an entity resource request like http://api.evri.com/v1/person/barack-obama-0x16f69. Note: now parse the properties and display as needed; for example, the property with name wikipedia_paragraph can be used as a description for each displayed entity.

Get recommended articles based on text

Description

Consider a scenario where we wish to display a list of articles related to a body of text.

Solution steps

1 Call the Get entity network about some text resource like http://api.evri.com/v1/media/entities?uri=http://www… to get an entity network.

2 Take the query token corresponding to the entire graph and apply to the Get media about an entity resource. For example if the returned results are:

      < graph >
      < queryToken >
      tVL ...
      < /queryToken >
      < entities >
      ...
      < /entities >
      < /pair >
      < /pairs >
      < /graph >

formulate a subsequent request like http://api.evri.com/v1/media/related?queryToken=tVL…

3 Parse the article results and display

Get recommended videos for an entity based on text

Consider a scenario where we wish to display a list of videos related to a body of text and the top entity identified within that text.

Solution steps

1 Call the Get entity network about some text resource like http://api.evri.com/v1/media/entities?uri=http://www… to get an entity network.

2 Take the query token corresponding to the highest scoring entity and apply to the Get media about an entity resource. For example if the returned results are:

      < graph >
      < queryToken >
      tVL ...
      < /queryToken >
      < entities >
      < entity score="85.0" href="/organization/pearl-jam-0x130e2" >
      < name >Pearl Jam< /name >
      −
      < queryToken >
      nZD...
      < /queryToken >
      < /entity >
      ...
      < /entities >
      < /pair >
      < /pairs >
      < /graph >

formulate a subsequent request like http://api.evri.com/v1/media/related?type=video&queryToken=nZD…

3 Parse the video results and display

Get recommended articles for an entity

Description

Consider a scenario where we wish to display a list of recommended articles for a given entity. In addition, we wish the entity itself to be bolded in the resulting article snippets, and any other entities present in the article snippets to be linked through to other entity pages. Finally, we want to include a list of all the top entities present in the article (i.e. not just in the snippet) and include links to those entities.

Solution steps

1 Call Get media about an entity resource like http://api.evri.com/v1/person/robert-mugabe-0x2446e/media/related?type=article&includeMatchedLocations=true&includeTopEntities=true or http://api.evri.com/v1/location/iran-0x2324c/relations/facet/country/location/united-states-0x2ae4b.xml?media=articles&includeMatchedLocations=true&includeTopEntities=true to receive a list of articles. Note: the includeMatchedLocations input parameter must be set to true to receive information used to bold and link to key entities in the summary snippet. Also note that the includeTopEntities input parameter must be set to true to receive information used to list the top entities found in the article.

2 For each returned article, note that key properties for display are present such as the article title, source URL link information, the article author, publication date, a select piece of content (i.e. content snippet), and sometimes a thumbnail image corresponding to the article.

3 For each returned article, note that titleMatchedLocations and contentMatchedLocations are present. These matched locations, or matchedLoc, point to key words and phrases that can be bolded and in some cases linked to other entities. For example, if we have the following article returned from the request http://api.evri.com/v1/person/robert-mugabe-0x2446e/media/related?type=article&includeMatchedLocations=true:

      < article >
        < author >Stuff< /author >
        < link href="/log/click?url=http%3A%2F%2Fwww.stuff.co.nz%2Fworld%2Fafrica%2F2524134%2FMugabe-power-share-defended" type="EIDF" hostName="www.stuff.co.nz" path="/world/africa/2524134/Mugabe-power-share-defended" / >
        < published >22 Jun 2009 02:37:11 GMT< /published >
        < title >Mugabe power-share defended< /title >
        < titleMatchedLocations >
          < matchedLoc startPtr="0" endPtr="5" / >
        < /titleMatchedLocations >
        < content >
      ...Morgan Tsvangirai has defended his decision to enter a power-sharing government with President Robert Mugabe.   The two bitter rivals joined in a coalition government in February.
        < /content >
        < contentMatchedLocations >
          < matchedLoc startPtr="3" endPtr="19" href="/person/morgan-tsvangirai-0x32697" matchType="nonQueryEntity" / >
          < matchedLoc startPtr="98" endPtr="110" href="/person/robert-mugabe-0x2446e" matchType="queryEntity" / >
        < /contentMatchedLocations >
        < thumbnail url="http://img.evri.com/feeds/nV_SLPKWHGJD-zjiUZlIA8e6mmJxkA/th.jpg" height="60" width="80" / >
      < /article >

we can note that the matchedLoc present in the titleMatchedLocations indicates that characters 0 to 5 corresponding to “Mugabe” in the title property should be bolded. In addition, in the contentMatchedLocations property, href attributes are present indicating that the referenced matchedLoc corresponds to the specified entity. So, for example, the first matchedLoc indicates that characters 3 to 19 correspond with the string “Morgan Tsvangiri” and the href /person/morgan-tsvangirai-0x32697 in the content snippet. This means we could, for example, include a link to a description of Morgan Tsvangiri by making a Get information about an entity call like http://api.evri.com/v1/person/morgan-tsvangirai-0x32697. Finally, the matchType attribute indicates whether the matchedLoc points to a queryEntity, nonQueryEntity, or a keyword. This is important since you may want to bold the entity whose page your user is already on (i.e. queryEntity) and any other matching keywords; in addition, you may wish to include a link to any other entity (i.e. nonQueryEntity) which happens to be present in the content snippet.

4 For each returned article, note that topEntities are listed. These entities include a ranked list of the people, places or things found anywhere in this article. These entities can now be linked to and listed similar to the method followed in the step above.

Code Samples

This section shows you how to get started in a select set of programming languages using the Evri API. Most languages not listed here can also easily be used to use the Evri API. You can replace the specified resource URI with any Evri API compatible URI.

Ruby Example

      def getURIListForPopularZeitgeistAll
             endpoint =Net::HTTP.new("api.evri.com")
             response = endpoint.get('/v1/zeitgeist/entities/person/popular')      
             document = REXML::Document.new(response.body)
             document = REXML::Document.new(response.body)    
             @entities= Array.new
              document.elements.each("zeitgeist/entities/person/popular") { |entity| @entities <<  entity.attributes["href"] }
             @entities 
      end

Java Example

This example shows how to use Java and the JSON library available at: http://www.json.org/java/

       URL restUrl = new URL("http://api.evri.com/v1/zeitgeist/entities/person/popular");
       URLConnection connection = restUrl.openConnection();
      
       String line;
       StringBuilder builder = new StringBuilder();
       BufferedReader reader = new BufferedReader(new InputStreamReader(connection.getInputStream()));
       while((line = reader.readLine()) != null) {
        builder.append(line);
       }
      
       JSONObject json = new JSONObject(builder.toString());
       // you can now use the json object to process the results

This example uses the java.net library to get a String object from a URI.

      public String GetResponse( String  uri ) {
          String response = null;
          try {
               URL uriToCall = new URL(uri);
               URLConnection connection;
               try {
                    connection = uriToCall.openConnection();
                    BufferedReader urlResponse = new BufferedReader(new InputStreamReader(
                    connection.getInputStream()));
                    StringBuilder sb = new StringBuilder();
                    String line = null;
                    while ((line = urlResponse.readLine()) != null) {
                      sb.append(line);
                    }
                    response= sb.toString();
                } catch (IOException e) {
                  e.printStackTrace()
                 //log here
                }
          } catch (MalformedURLException e) {
            // TODO Auto-generated catch block
           e.printStackTrace();
          } 
          return response;
      }

You can also use a tooolkit like XStream to read the response as objects instead of the JSON libraries. This will be helpful if you prefer the XML response type. The JAX-RS specification is a server side specification which may be appropriate; in addition there are tools like the RestEasyClientFramework that can be used to call rest services.

PHP Example

This example shows how to use PHP version (5.2) 

      $resturl = "http://api.evri.com/v1/zeitgeist/entities/person/popular";
      
      // call the service 
      $ch = curl_init();
      curl_setopt($ch, CURLOPT_URL, $resturl);;
      $body = curl_exec($ch);
      curl_close($ch);
      
      // after this the json object can be used
      $json = json_decode($body);

Flash Example using Action Script 3

      var restservice:HTTPService = new HTTPService();
      restservice.url = 'http://api.evri.com/v1/zeitgeist/entities/person/popular';
      restservice.addEventListener(ResultEvent.RESULT, onServerResponse);
      restservice.send();
      
      private function onServerResponse(event:ResultEvent):void {
        try {
          var json:Object = JSON.decode(event.result as String);
        } catch(ignored:Error) {
            //handle this
        }
        //the json object has what you will need
      }

Feedback and Troubleshooting

Please use the developer forum to tell us about your successes and challenges. We will respond to your questions as promptly as we can.

Known Issues