ID Converter API

The ID Converter API is the backend web service that is used by the PMCID - PMID - Manuscript ID - DOI Converter. This API allow you to programmatically convert between the various IDs used in our system.

The base URL of the service is https://www.ncbi.nlm.nih.gov/pmc/utils/idconv/v1.0/. This is shown as "service-root" in the examples below.

When using this API programmatically, we request that you use the tool and email parameters to identify the application making the request. tool should be the name of the application, as a string value with no internal spaces. email should be the e-mail address of the maintainer of the tool, and should be a valid e-mail address. For brevity, these have been left out of the displayed URLs in the examples below.

The ids parameter specifies the article IDs that you want to convert. By default, the service will determine the type of the IDs from their format. In any given service call, all of the IDs must be of the same type.

Here are examples, one for each type of ID that the service understands:

PMID: service-root?ids=23193287
PMCID: service-root?ids=PMC3531190
Manuscript ID: service-root?ids=NIHMS311352
DOI: service-root?ids=10.1093/nar/gks1195
Versioned identifier: service-root?ids=PMC2808187.1

Use commas to separate multiple IDs:

service-root?ids=PMC3531190,PMC3245039

This service allows for conversion of up to 200 IDs in a single request. If you have a larger number of IDs, split your list into smaller subsets. Another option for bulk-conversion of identifiers in the PMC system is to download the PMC-ids.csv.gz file, as described on the FTP Service page.

You can override ID type auto-detection behavior by using the idtype parameter. Valid values are "pmcid", "pmid", "mid", and "doi". For example, the following lets you specify PMCIDs as simple numeric values. If the idtype parameter is not used, PMCIDs must have the "PMC" prefix, in order to distinguish them from PMIDs.

service-root?ids=14900&idtype=pmcid

Examples

Article with versions

A typical article might have two versions associated with it, one of which is the author manuscript, and the other is the final published version.

service-root?ids=PMC1193645

<pmcids status="ok">
  <request idtype="pmcid" pmcids="" versions="yes" showaiid="no">
    <echo>tool=my_tool;email=my_email%40example.com;ids=PMC1193645</echo>
  </request>
  <record requested-id="PMC1193645" pmcid="PMC1193645" pmid="14699080" 
      doi="10.1084/jem.20020509">
    <versions>
      <version pmcid="PMC1193645.1" mid="NIHMS2203"/>
      <version pmcid="PMC1193645.2" current="true"/>
    </versions>
  </record>
</pmcids>

Note that each version of the article is listed within its own <version> element, and that MIDs, which correspond to specific versions, are always given there. The current attribute specifies which version is rendered by default by the PMC system, when the article is accessed by its PMCID (for example, here).

Suppressing version information

If the application doesn't need the MIDs or information about the versions of an article, it can suppress it by using the parameter versions=no. For example:

service-root?ids=PMC1193645&versions=no

<pmcids status="ok">
  <request idtype="pmcid" pmcids="" versions="no" showaiid="no">
    <echo>tool=my_tool;email=my_email%40example.com;ids=PMC1193645;versions=no</echo>
  </request>
  <record requested-id="PMC1193645" pmcid="PMC1193645" pmid="14699080" 
      doi="10.1084/jem.20020509"/>
</pmcids>

Article under embargo

If an article is under embargo, then that information will be conveyed as in the following example. (Note that these examples are, by necessity, time-sensitive. If the embargo period has passed, the results will be different than those shown here.)

service-root?ids=PMC4143528

<pmcids status="ok">
  <request idtype="pmcid" pmcids="" versions="yes" showaiid="no">
    <echo>tool=my_tool;email=my_email%40example.com;ids=PMC4143528</echo>
  </request>
  <record requested-id="PMC4143528" pmcid="PMC4143528" pmid="25041724" 
      doi="10.1111/apt.12862" live="false" release-date="2015-09-01">
    <versions>
      <version pmcid="PMC4143528.1" mid="NIHMS613292" live="false" 
          release-date="2015-09-01"/>
    </versions>
  </record>
</pmcids>

Some articles are available as manuscripts while the final published version is under embargo. For example,

service-root?ids=PMC3258307

<pmcids status="ok">
  <request idtype="pmcid" pmcids="PMC3258307" versions="yes" showaiid="no">
    <echo>tool=my_tool;email=my_email%40example.com;ids=PMC3258307</echo>
  </request>
  <record requested-id="PMC3258307" pmcid="PMC3258307" pmid="22091849"
          doi="10.1111/j.1475-6773.2011.01339.x">
    <versions>
      <version pmcid="PMC3258307.1" mid="NIHMS325754" current="true"/>
      <version pmcid="PMC3258307.2" live="false" release-date="2014-02-01"/>
    </versions>
  </record>
</pmcids>

Other formats

The service can provide output in a number of formats, as specified by the format parameter, which can be one of "html", "xml", "json", or "csv". "xml" is the dafault, and several examples of this response format are given above. Examples of each of the other formats is shown below.

JSON

service-root?ids=PMC2883744&format=json

{
  "status": "ok",
  "responseDate": "2013-09-23 14:28:14",
  "request": "tool=my_tool;email=my_email%40example.com;ids=PMC2883744;format=json",
  "records": [
    {
      "pmcid": "PMC2883744",
      "pmid": "20495566",
      "doi": "10.1038/ng.590",
      "versions": [
        {
          "pmcid": "PMC2883744.1",
          "mid": "UKMS29888"
        },
        {
          "pmcid": "PMC2883744.2",
          "mid": "NIHMS198092",
          "current": true
        }
      ]
    }
  ]
}

CSV

service-root?ids=PMC2883744&format=csv

"PMID","PMCID","DOI","Version","MID","IsCurrent","IsLive","ReleaseDate","Msg"
"20495566","PMC2883744","10.1038/ng.590","PMC2883744.1","UKMS29888",0,1,"",""
"20495566","PMC2883744","10.1038/ng.590","PMC2883744.2","NIHMS198092",1,1,"",""
Support Center

Last updated: Tue, 26 Aug 2014