The Daylife API exposes metadata about and connections around a core set of News Objects. These News Objects and their relationships enable developers to build applications that reveal new kinds of information to users and enable users to explore the landscape of news.
Our goal is to enable developers to ask rich questions about news content, and to build applications around those questions and their answers.
The Daylife API allows you to access various methods that retrieve information about the following classes of News Objects:
Each text-based item made available by a source that Daylife indexes has a corresponding representation in the Daylife API. These include blog posts, news articles, press releases, transcripts,
and so on.
Which articles from this week's European Press cover the same subject as this
morning's lead article in the New York Times?
Quotations extracted from articles that Daylife indexes are attributed to individuals, associated with topics, and made available via a set of API calls.
What has Angelina Jolie said about Darfur this month?
Daylife's platform organizes content according to things Daylife knows about in the world: People, Places, Companies, Organizations, and so on.
What were the most relevant articles published about Prince Charles this April?
The Daylife API supports full text search of indexed content, and enables retrieval of the context created by the results of those searches.
Which organizations are mentioned most in recent articles about Solar Power?
Each instance of an Article, Image, Quote, or Topic News Object has a unique ID. These IDs can be obtained initially through the search method calls. For example, the search method call search_getRelatedArticles returns articles containing a query string each with a unique article_id. These unique IDs can then be used to call article_getRelatedQuotes to obtain additional content about or related to that specific article. This principle of unique IDs applies to all News Objects.
Note: Some calls accept multiple unique IDs. In other cases, alternative mechanisms exist to access News Objects other than unique IDs. See the Constructing Requests section and the individual calls in the reference section for more details.
Timestamps are returned by the Daylife API and are provided to the Daylife API as parameters to News Object method calls. Timestamps are formatted as epoch values or ISO 8601 strings.
In all cases, Timestamps provided to and returned by the Daylife API are expressed in Universal Time (UTC).
Epoch Value Timestamp
Date and time represented by an integer indicating the number of seconds elapsed since Jan 1, 1970.
ISO 8601 Timestamps
A string in the form YYYY-MM-DD hh:mm:ss, where date and time are separated by an empty space:
YYYY - four digit number representing the year.
MM - two digit number representing the month. Values are in the range 01 to 12.
DD - two digit number representing the day. Values are in the range 01 to 31.
hh - two digit number representing the hour in 'military time'. Values are in the range 00 to 23.
mm -two digit number representing the minute. Values are in the range 00 to 59.
ss - two digit number representing the whole seconds. Values are in the range 00 to 59.
Timestamps in Daylife API Requests
The Daylife API accepts two request parameters that are timestamps -- start_time and end_time.
start_time always chronologically precedes the end_time. For example, if start_time is "2007-01-01", then end_time must be sometime chronologically after Jan 1, 2007.
Each parameter can accept either an integer epoch value or an ISO 8601 formatted string (see earlier discussion on Timestamps).
Omitted parts of ISO 8601 formatted timestamps fall back to default values with the following rules:
- Omitted parts of start_time default to their minimum values. For example:
- 2004-03 defaults to 2004-03-01 00:00:00
- 2004-03-05 23 defaults to 2004-03-05 23:00:00
- If start_time is omitted entirely, it is defaulted to (end_time - 1 month)
- Omitted parts of end_time default to their maximum values. For example:
- 2004-03 defaults to 2004-03-31 23:59:59
- 2004-03-05 23 defaults to 2004-03-05 23:59:59
- If end_time is omitted entirely, it is defaulted to the current time (now).
Timestamps in Daylife API Responses
Timestamps in Daylife API responses are returned as two separate (but logically identical) response parameters for convenience:
- As an epoch integer value in the timestamp_epoch parameter.
- In an ISO 8601 string notation in the timestamp parameter.
The Daylife API is accessed by calling News Object methods and passing parameters via HTTP GET.
Requests are composed by constructing a URL that specifies an API endpoint and a list of input parameters. Input parameters are provided as URLEncoded name value pairs.
A Daylife API endpoint is specified like this:
Input parameters are appended to the Daylife API endpoint as '&' separated list of name-value pairs of arguments, added to the query string using the standard HTTP GET formatting.
So a fully expressed call to the Daylife API looks like this:
For example, a call to search for articles containing the text "iraq war" is defined as follows:
where <accesskey> is your assigned access key, and <signature> is replaced by an actual MD5 security signature as explained below.
The above request may return multiple articles in its response each with a unique ID (discussed earlier). A request for quotes related to one of these articles would look like this:
If quotes from multiple articles are desired, multiple articles may be provided as multiple article_id parameter name-value pairs as follows:
Authentication and Signature Creation
DayAPI users are provided with two authentication credentials to call Daylife API methods:
- An Access Key
Identifies the user and will be sent in every API call in the query string parameter 'accesskey'
- A Shared Secret
A shared key between Daylife and the API user. This key should never be sent in an API call.
Each Daylife API call has a core input at its heart (see earlier discussion on Unique IDs). The specific nature of this core input depends on the News Object being accessed.
- In most cases, the core input is an id (e.g. topic_id, article_id, quote_id, image_id) which uniquely represents the News Object being accessed.
- For Topics, a name parameter may be used in lieu of a topic_id.
- In the case of the Search service, the core identifier is the search query term itself.
- For Articles, a url parameter may be used in lieu of an article_id.
In order to authenticate, Daylife API users create a signature using the access key, the shared secret, and the core input for the call at hand. That signature string is then used in the API call parameter named signature. The signature parameter is calculated as follows:
Signature = md5(concatenation of access key, the shared secret, and the core input)
So, for example in PHP:
Note that the core input should NOT be urlencoded for the purposes of signature generation.
If an API call accepts multiple values for the core input parameter (e.g. article calls can accept multiple article ids or multiple article urls), the $coreinput for signature generation is a concatenated string of alphabetically sorted list of the core input values.
For e.g., If I am calling article_getInfo for article ids 0eQ1fovglo368, 0fP60GB2Qy9EX and 08Dh1Ij97064e, to create signature in PHP:
Some more discussion about creating signatures here.
Data formats returned by the Daylife API
The Daylife API returns data in a variety of formats, depending on the value of <protocol> you specify in your constructed request. In this version of the Daylife API, there are 3 response formats are available:
Returns data as an xml formatted document. We use this format in the documentation that follows, since itâ€™s the most easily read.
Returns data in a form directly deserializable to native PHP objects.
Again, the only thing you need to change is the protocol you specify in your method call. So, for instance:
Each returns the same data, only in different formats.
Daylife tracks news from thousands of sources across the world. Sources include mainstream news such as the New York Times, blogs such as BuzzMachine, and other types of news content sources such as Getty Images for photos.
For your application, however, you may wish to restrict the results you retrieve to suppress certain sources, or to only feature content from specific sources.
Daylife API users can restrict the results of the Daylife APIs to sources of their choice by creating and accessing source filters â€“ i.e., whitelists or blacklists of news and image sources. Source filters can be defined in two ways: as a predefined set or as a runtime defined set , which you provide in the context of your Daylife API call.
You can have as many source filters as you like, which you can use for various purposes. For example:
- To limit blog content in your results
- To retrieve content only from your publication
- To filter out content offered by publications you despise
You can read more about how to use source filters here.
All parameter values in the request should be UTF-8 encoded. The response from the DayPI is also UTF-8 encoded.
Encoding Daylife API Requests
All Daylife API requests must be made with URL encoded parameter values.
For example query="George Bush" must be encoded as query=%22George%20Bush%22 (or query=%22George+Bush%22).
Wikipedia has a nice overview of URLEncoding (http://en.wikipedia.org/wiki/Percent-encoding).
You can find hard-core documentation in RFC3986 on the IETF site (http://tools.ietf.org/html/rfc3986).
Encoding Daylife API Responses
All responses from the Daylife API return data in UTF-8 encoding.
You can read more about UTF-8 encoding in a Wikipedia article at http://en.wikipedia.org/wiki/UTF-8 or in the IETF's RFC3629 at http://tools.ietf.org/html/rfc3629
Limit, Offset, and Sort Parameters
The Daylife API provides the capability to paginate through and sort returned results.
A Daylife API user can page through results by specifying positive integer values for the limit and offset request parameters. For example:
returns 10 rows of results starting at index 0. Similarly, offset=10&limit=10 returns the next 10 rows in the results starting at index 10.
Daylife API users can also sort results by specifying a sort parameter in the request. For example:
Most of the Daylife API methods allow for sorting by chronologically ascending 'date' or by weighted 'relevance'. For specific information about supported sorting options, refer to the News Object method calls themselves as well as the section/appendix on search query syntax which includes more information on relevance sorting and ways of influencing it.
Parameters that allow multiple name-value pairs
There are parameters in the Daylife API that accept multiple values. They can be expressed as
If a core input parameter can accept multiple values, the methodology to create a signature is specified here.
Versioning and Compatibility Levels
In order to accommodate an evolving Daylife API while ensuring backwards compatibility (we don't want your stuff breaking!), Daylife uses an explicit versioning scheme.
Each Daylife API call endpoint has a version number and every request explicitly specifies the version number in the request URL.
The Daylife API uses a Major.Minor.Patch version scheme, like so:
A major change introduces dramatically new and or different functionality, and includes changes in syntax that will almost certainly break existing applications.
The Minor level increments with added features released. A developer should expect to see new features in the Daylife API. Minor level changes are NOT guaranteed to be backwards compatible.
The Patch level increments when bug fixing a Minor release. These fixes to existing calls are guaranteed to be backwards compatible for the corresponding Major and Minor level. For example, if a new version 1.4.2 of the Daylife API is released, all 1.4 calls will continue to work as before.
Daylife keeps multiple versions of the API running simultaneously, so that your application can continue running against an existing compatibility level until that level is explicitly discontinued.
In order to make sure that the broad community of users has access to the Daylife API for free, we cap each developer's daily usage of the Daylife API.
At this time, you're allowed to make 5000 calls per day to the Daylife API.
If your usage will exceed this cap, you should contact us.
Typically, Premium Licenses of the Daylife API are not subject to daily usage caps.