Skip to main content
PMC home page

ID Converter API

The ID Converter API is the backend web service that is used by the PMC ID Converter. This API allows 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.

Parameters

Required Parameters: tool and email

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 your application, as a string value with no internal spaces.
    • email should be the e-mail address of the maintainer of your tool, and should be a valid e-mail address.

For brevity, these have been left out of the displayed URLs in the examples below.

ids Parameter

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:

Multiple IDs

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.

idtype Parameter

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

versions Parameter

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

format Parameter

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 default

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=PMC8131428

<pmcids status="ok">
<request idtype="pmcid" pmcids="" versions="yes" showaiid="no">
<echo>tool=my_tool;email=my_email%40example.com;ids=PMC8131428</echo>
</request>
<record requested-id="PMC8131428" pmcid="PMC8131428" pmid="34040925" doi="10.1007/s13205-021-02724-9" 
live="false" release-date="2022-06-01">
<versions>
<version pmcid="PMC8131428.1" live="false" release-date="2022-06-01"/>
</versions>
</record>
</pmcids>

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

service-root?ids=PMC9170831

<pmcids status="ok">
  <request idtype="pmcid" pmcids="PMC9170831" versions="yes" showaiid="no">
    <echo>tool=my_tool;email=my_email%40example.com;ids=PMC11322416</echo>
  </request>
  <record requested-id="PMC9170831" pmcid="PMC9170831" pmid="34875719" doi="10.1111/joa.13605">
    <versions>
      <version pmcid="PMC9170831.1" mid="NIHMS1760531" current="true"/>
      <version pmcid="PMC9170831.2" live="false" release-date="2024-11-01/>
    </versions>
  </record>
</pmcids>

Examples of 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 default, and several examples of this response format are given above. Examples of each of the other formats is shown below.

JSON

service-root?ids=PMC7611378&format=json

{
 "status": "ok",
 "responseDate": "2021-07-28 17:40:29",
 "request": "tool=my_tool;email=my_email%40example.com;ids=PMC7611378;format=json",
 "records": [
   {
    "pmcid": "PMC7611378",
    "pmid": "27102758",
    "doi": "10.1136/archdischild-2015-309789",
    "versions": [
      {
       "pmcid": "PMC7611378.1",
       "mid": "EMS130996",
       "current": "true"
      }
    ]
   }
 ]
}

CSV

service-root?ids=PMC7611378&format=csv

"PMID","PMCID","DOI","Version","MID","IsCurrent","IsLive","ReleaseDate","Msg"
"27102758","PMC7611378","10.1136/archdischild-2015-309789","PMC7611378.1","EMS130996",1,1,"",""