Skip to main content

Bulk Data and API

Updated

Bulk Data

Bulk data can be accessed at the iCite database snapshot repository.

API

/api/pubs

List publications, including data about each one.

Optional query parameters:

  • limit: how many publications to return. The maximum allowed is 200.
  • offset: only return publications with a PMID greater than this.
  • year: only return publications from the given year.
  • pmids: only return publications with the given PubMed IDs. Separate multiple IDs with commas to request up to 200 at a time. If this parameter is provided, all other parameters are ignored.
  • fl: only return publications with the given fields. Separate multiple fields with commas (no space). Field names are very specific and listed in Response example below. No fl param will return all fields.
  • format: return data as a csv (comma separated value) by specifying format=csv rather than the default JSON.
  • legacy: set to false to return actual field names from database (see look up table below) 

Example: /api/pubs?pmids=28968381,28324054,23843509&fl=pmid,year,title,apt,relative_citation_ratio,cited_by_clin
Example: /api/pubs?offset=23456789&limit=10&format=csv

 

/api/pubs/{pmid}

Get data on a specific publication. Example: /api/pubs/23456789

/api/pubs?pmids={pmid1,pmid2...}

Get data on multiple specific publications.
Example: /api/pubs?pmids=23456789,27599104
Example: /api/pubs?pmids=23456789,27599104&format=csv

Code Examples

Get the data for a specific PMID by visiting /api/pubs?pmids=23456789:

Response

    {
      "_id": "23456789",
      "authors":  […],
      "doi": "10.1002/cncr.27976",
      "pmid":   23456789, 
      "title": "Hospital volume is associated with survival but not multimodality therapy in Medicare patients with advanced head and neck cancer.",
      "animal": 0,
      "apt": 0.75,
      "human": 1,
      "citedByPmidsByYear":  […],
      "citedByClinicalArticle": true,
      "year": 2013,
      "journal": "Cancer",
      "is_research_article": true,
      "relative_citation_ratio": 1.60818336106796,
      "nih_percentile": 67.5,
      "molecular_cellular": 0,
      "is_clinical": false,
      "citation_count": 47,
      "citations_per_year": 3.91666666666667,
      "expected_citations_per_year": 2.43546025999529,
      "field_citation_rate": 5.83260798611484,
      "provisional": false,
      "x_coord": 0,
      "y_coord": 1,
      "cited_by_clin": [25488965, 29180076],
      "cited_by": […],
      "references": […]
    }

Python

import requests


response = requests.get(
    "/".join([
        "https://icite.od.nih.gov/api",
        "pubs",
        "23456789",
    ]),
)
pub = response.json()
print(pub)

JavaScript

var request = new XMLHttpRequest();
request.open(
    "GET",
    [
        "https://icite.od.nih.gov/api",
        "pubs",
        "23456789",
    ].join("/")
);
request.responseType = "json";
request.onload = function () {
    console.log(request.response);
};
request.send();

Using database fields (legacy=false)

Get the data for a specific PMID by visiting /api/pubs?pmids=23456789&legacy=false:

Response

    {
      "_id": "23456789",
      "authors": […],
      "doi": "10.1002/cncr.27976",
      "iCiteArticle": true,
      "journalNameIso": "Cancer",
      "pmid": 23456789,
      "pubYear": 2013,
      "title": "Hospital volume is associated with survival but not multimodality therapy in Medicare patients with advanced head and neck cancer.",
      "acr": 3.91666666666667,
      "citedByPmidCount": 47,
      "citedByPmids": […],
      "citedPmids": […],
      "ecr": 2.43546025999529,
      "fcr": 5.83260798611484,
      "rcr": 1.60818336106796,
      "animal": 0,
      "apt": 0.75,
      "human": 1,
      "molCell": 0,
      "xCoord": 0,
      "yCoord": 1,
      "citedByPmidsByYear": […],
      "nihRcrPercentile": 67.5,
      "citingClinicalPmids": […],
      "isClinicalArticle": false,
      "citedByClinicalArticle": true,
      "rcrIsProvisional": false
    }

Field mapping

  Legacy: Database field name 
  "pmid": "pmid"
  "year": "pubYear"
  "title": "title"
  "authors": "authors"
  "journal": "journalNameIso"
  "is_research_article": "iCiteArticle"
  "relative_citation_ratio": "rcr"
  "nih_percentile": "nihRcrPercentile"
  "human": "human"
  "animal": "animal"
  "molecular_cellular": "molCell"
  "apt": "apt"
  "is_clinical": "isClinicalArticle"
  "citation_count": "citedByPmidCount"
  "citations_per_year": "acr"
  "expected_citations_per_year": "ecr"
  "field_citation_rate": "fcr"
  "provisional": "rcrIsProvisional"
  "x_coord": "xCoord"
  "y_coord": "yCoord"
  "cited_by_clin": "citingClinicalPmids"
  "cited_by": "citedByPmids"
  "references": "citedPmids"
  "doi": "doi"
  "last_modified": "lastModified"

 

Content Type

By default, responses are JSON. CSV responses are supported as well and can be requested via Accept: text/csv.

How to Post

It is possible to POST from another site or application to iCite to construct a sharable URL. A sample request looks like the following:

URL: https://icite.od.nih.gov/iciterest/direct-search

JSON Request:

{ 
    "pmids": ["27548312", "27618447", "29256494"],
    "userType": "API", 
    "searchType": "Third Party" 
}

JSON Response:

{ 
    "id": "04161094f1b04dfb8fff62ec93bf7dd5" 
}

You may then construct the URL to results like so: https://icite.od.nih.gov/results?searchId=04161094f1b04dfb8fff62ec93bf7dd5

 

Feedback

Please send any feedback to iCite@mail.nih.gov.

 

Related articles