Timestamps in feedly APIs

[david]

  This post clarifies the timestamps used by feedly APIs.

  All timestamps returned by feedly are Unix epoch timestamps, in milliseconds (1).

  Entries returned by feedly APIs (streams, mixes, entries etc) will contain up to five timestamps:

1. "crawled": this timestamp indicates when the entry was added to feedly. This timestamp is immutable. It is used to sort entries in feed streams.
2. "recrawled" (optional): this timestamp indicates that the entry was updated on feedly because of a change in the source feed.
3. "actionTimestamp" (tag streams only): this timestamp indicates when the entry was tagged by the user. It is used to sort entries in tag streams.
4. "published": this timestamp is converted from the published date reported by the RSS or Atom feed. This timestamp is not reliable. Some feeds will report dates in the future, or dates years back in the past, or the same date for all articles.
5. "updated" (optional): this timestamp is converted from the updated date reported by the RSS or Atom feed. This timestamp is not reliable, for the same reasons as above.

  It is not recommended to show the "published" or "updated" timestamps to the user: the dates are often wrong. Instead, show the "crawled" and "recrawled" for feed streams, and "actionTimestamp" for tag streams (which is the timestamp when the user tagged the entry).

  The "newerThan" parameter in streams and in markers APIs is compared to the "crawled" timestamp for feed streams ("actionTimestamp" for tag streams). Never pass a "published" or "updated" timestamp for "newerThan": doing so will cause the server to skip entries, or return entries previously returned. Always use the "crawled" timestamp from an entry ("actionTimestamp" when requesting a tag stream). These are accurate, and guarantee you will not miss a new article(2). You can also use the "updated" timestamp from previous stream results:

  Questions and suggestions are welcome.

(1) https://en.wikipedia.org/wiki/Unix_time

(2) articles crawled before "newerThan", but updated after "newerThan" will not be returned however: updates do not change the "crawled" date.

-- 

David Chatenay

Feedly