Endpoints for retrieving a timeline

This type of endpoint enables the retrieval of a timeline of the number of views, downloads or shares for a specific item.

Authorization

Basic HTTP authentication is required for timeline endpoints within the scope of an institution.

Endpoint format

For items outside an institution scope the endpoints have the format:

/timeline/{granularity}/{counter}/{item}/{item_id}

and inside an institution scope they have the format:

/{institution}/timeline/{granularity}{counter}/{item}/{item_id}

where granularity is one of year, month, day or total , counter is one of views, downloads or shares and item is one of article, author, collection, group or project.

The results on this endpoint can be filtered further by a start_date and end_date and a specified category or item_type. By default, start_date and end_date are set to reflect the events of the last month. The supplementary filters can be provided in the request parameters.

Request parameters

The following table describes the optional parameters:

Parameter Comments
start_date By default this is set to the 1st of the current month.
end_date By default this is set to today.
sub_item Can be one of category and item_type. Acts as a filter on the result.
sub_item_id Required if sub_item is also specified.

Examples

Daily timeline of downloads for an unaffiliated article

Request

GET https://stats.figshare.com/timeline/day/downloads/article/23

Response

HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8

{
  "timeline": {
    "2015-07-01": 7,
    "2015-07-02": 3,
    "2015-07-09": 1,
    "2015-07-15": 3,
    "2015-07-16": 2,
    "2015-07-18": 1
  }
}

Yearly timeline of views for an article associated to an institution

Request

GET https://stats.figshare.com/monash/timeline/year/views/article/2000000?start_date=2013-01-01&end_date=2015-08-01
Authorization: Basic dGhpcyBpcyBub3QgdGhlIHJlYWwgcGFzc3dvcmQsIGZvb2wh

Response

HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8

{
  "timeline": {
    "2013": 16,
    "2014": 23,
    "2015": 12
  }
}

Monthly timeline of shares for items in a specified institutional group, matching a specified category

Request

GET https://stats.figshare.com/monash/timeline/month/shares/group/10?sub_item=category&sub_item_id=2&start_date=2014-01-03&end_date=2014-05-12
Authorization: Basic dGhpcyBpcyBub3QgdGhlIHJlYWwgcGFzc3dvcmQsIGZvb2wh

Response

HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8

{
  "timeline": {
    "2014-01": 3,
    "2014-02": 5,
    "2014-03": 18,
    "2014-04": 4,
    "2014-05": 2
  }
}

Daily timeline of views for datasets found in a specified institutional group

Request

GET https://stats.figshare.com/monash/timeline/day/views/group/10?sub_item=item_type&sub_item_id=dataset&start_date=2014-03-01&end_date=2014-03-04
Authorization: Basic dGhpcyBpcyBub3QgdGhlIHJlYWwgcGFzc3dvcmQsIGZvb2wh

Response

HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8

{
  "timeline": {
    "2014-03-01": 10,
    "2014-03-02": 14,
    "2014-03-03": 15,
    "2014-03-04": 9
  }
}

Total timeline of views for a collection associated to an institution

Request

GET https://stats.figshare.com/lboro/timeline/total/views/collection/15?start_date=2014-01-02&end_date=2014-03-05
Authorization: Basic dGhpcyBpcyBub3QgdGhlIHJlYWwgcGFzc3dvcmQsIGZvb2wh

Response

HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8

{
  "timeline": {
    "total": 10
  }
}

Timeline with missing request parameter

Request*

GET https://stats.figshare.com/lboro/timeline/month/views/group/1?sub_item=category&start_date=2014-01-01&end_date=2015-02-03
Authorization: Basic dGhpcyBpcyBub3QgdGhlIHJlYWwgcGFzc3dvcmQsIGZvb2wh

Response

HTTP/1.1 400 Bad Request
Content-Type: application/json; charset=UTF-8

{
  "data": {
    "missing_params": "sub_item_id",
    "parameters": {
      "end_date": "2015-02-03",
      "start_date": "2014-01-01",
      "sub_item": "category"
    },
    "path": "/lboro/timeline/month/views/group/1"
  },
  "code": "MissingParams",
  "message": "Missing required params: sub_item_id"
}