UCAR Citation API Guide

This API allows users to retrieve citation information for UCAR assets that have been assigned a Digital Object Identifier (DOI). Responses are returned in Javascript Object Notation (JSON) by default, with the possibility of other formats being made available in the future. Filtering of results via query parameters is another planned future implementation.

This guide describes the various operations of the API and provides sample API calls and responses.

Retrieve a single DOI

Get citation data for a specific DOI.

GET /citations/doi/<DOI>
$ curl https://api.rda.ucar.edu/citations/doi/10.5065/D6M043C6

Response:

{"doi": "10.5065/D6M043C6", "total_citations": 353, "years": {"min": 2014, "max": 2023}}

  • total_citations: total number of citations found for the specified DOI
  • years: the minimum ("min") and maximum ("max") publication years for this DOI's citations

Annual citations counts:

GET /citations/doi/<DOI>/counts
$ curl https://api.rda.ucar.edu/citations/doi/10.5065/D6M043C6/counts

Response:

{"doi": "10.5065/D6M043C6", "counts": [{"2014": 2}, {"2015": 11}, {"2016": 12}, {"2017": 28}, {"2018": 55}, {"2019": 51}, {"2020": 56}, {"2021": 56}, {"2022": 81}, {"2023": 1}]}

  • counts: the annual citation counts for each year where there is at least one citation for this DOI

Filtering the annual counts:

GET /citations/doi/<DOI>/counts?min=2015&max=2018
$ curl https://api.rda.ucar.edu/citations/doi/10.5065/D6M043C6/counts?min=2015&max=2018

Response:

{"doi": "10.5065/D6M043C6", "counts": [{"2015": 11}, {"2016": 12}, {"2017": 28}, {"2018": 55}]}

  • min with no max implies that the maximum year is unbounded
  • max with no min implies that the minimum year is unbounded

Publications that have cited this DOI:

GET /citations/doi/<DOI>/publications
$ curl https://api.rda.ucar.edu/citations/doi/10.5065/D6M043C6/publications

Response:

{"doi": "10.5065/D6M043C6", "publications": [{"doi": "10.4236/acs.2014.44053", "year": 2014, "authors": ["Nicole M\\u00f6lders", "Cindy L. Bruy\\u00e8re", "Scott Gende", "Michael A. Pirhalla"], "title": "Assessment of the 2006-2012 Climatological Fields and Mesoscale Features from Regional Downscaling of CESM Data by WRF-Chem over Southeast Alaska", "publisher": "Scientific Research Publishing, Inc.", "xxxxx": {...}}, ...]}

  • publications: the detailed list of publications that have cited this DOI
      - doi: the DOI of the citing publication
      - year: the publication year
      - authors: the ordered list of authors of the publication
      - title: the title of the publication
      - publisher: the publisher of the publication
      - xxxxx: type of publication, as follows:

         book chapter (portion of a book):
    "book_chapter": {"ISBN": "9783319475929", "editors": ["Jennifer M Collins", "Kevin Walsh"], "title": "Hurricanes and Climate Change", "publisher": "Springer", "pages": "117-134"}
          - ISBN: the International Standard Book Number for the book
          - title: the title of the book
          - editors: the editors of the book
          - publisher: the publisher of the book
          - pages: the page range for this publication within the book

         journal article:
    "journal": {"title": "ACS", "volume": "04", "pages": "589-613"}
          - title: title of the journal article
          - volume: volume of the journal containing the article
          - pages: pages of the journal volume containing the article

         conference preprints or proceedings:
    "publication": {"title": "Energy Procedia", "pages": "164-168"}
          - title: title of the conference preprints or proceedings
          - pages: pages of the publication within the conference preprints or proceedings

Formatting the publications as a bibliography:

GET /citations/doi/10.5065/D6M043C6/publications?format=bibliography
$ curl https://api.rda.ucar.edu/citations/doi/10.5065/D6M043C6/publications?format=bibliography

Response:

{"doi": "10.5065/D6M043C6", "publications": ["Abdi-Oskouei, M., Pfister, G., Flocke, F., Sobhani, N., Saide, P., Fried, A., Richter, D., Weibring, P., Walega, J., & Carmichael, G. (2018). Impacts of physical parameterization on prediction of ethane concentrations for oil and gas emissions in WRF-Chem. Atmospheric Chemistry and Physics, 18, 16863-16883. https://doi.org/10.5194/acp-18-16863-2018", "Abdi\\u2010Oskouei, M., Carmichael, G., Christiansen, M., Ferrada, G., Roozitalab, B., Sobhani, N., Wade, K., Czarnetzki, A., Pierce, R., Wagner, T., & Stanier, C. (2020). Sensitivity of Meteorological Skill to Selection of WRF\\u2010Chem Physical Parameterizations and Impact on Ozone Prediction During the Lake Michigan Ozone Study (LMOS). Journal of Geophysical Research: Atmospheres, 125(5). https://doi.org/10.1029/2019JD031971", ..., "\u00c3\u0081lvarez, C. A., & Carbajal, N. (2019). Regions of influence and environmental effects of Santa Ana wind event. Air Quality, Atmosphere and Health, 12, 1019-1034. https://doi.org/10.1007/s11869-019-00719-3"]}

Top of guide

Retrieve the list of DOI minters

Get the list of DOI minters that are being tracked by this service.

GET /citations/minters
$ curl https://api.rda.ucar.edu/citations/minters

Response:

{"minters": ["rda", "eol", "ucar"]}

Top of guide

Retrieve a minter

Get information about a specific minter.

GET /citations/minter/<minter>
$ curl https://api.rda.ucar.edu/citations/minter/ucar

Response:

{"minter": "UCAR", "asset-types": ["dataset", "text", "software", "collection", "model", "service"], "publishers": ["UCAR/NCAR - CISL - CDP", "UCAR/NCAR Climate Data Gateway", ..., "Insurance Australia Group (IAG)"]}

  • asset-types: the list of asset-types that have at least one cited DOI
  • publishers: the list of UCAR publishers that have at least one cited DOI

Get the list, for a specific minter, of DOIs that have been cited at least once.

GET /citations/minter/<minter>/dois
$ curl https://api.rda.ucar.edu/citations/minter/ucar/dois

Response:

{"minter": "UCAR", "list": [{"doi": "10.26024/0cs0-ev98", "asset-type": "dataset", "publisher": "UCAR/NCAR - CISL - CDP"}, {"doi": "10.26024/5b58-nc53", "asset-type": "dataset", "publisher": "UCAR/NCAR Climate Data Gateway"}, ..., {"doi": "10.5065/ZGJD-9B02", "asset-type": "dataset", "publisher": "UCAR/NCAR - Research Data Archive"}]}

  • list: the list of DOIs for the specified minter having at least one citation
        - doi: the cited DOI
        - asset-type: the type of asset (e.g dataset, software, text, etc.)
        - publisher: the group within the specified minter that publishes the DOI

Filtering the list of DOIs:

GET /citations/minter/<minter>/dois?<filter>=<value>
$ curl https://api.rda.ucar.edu/citations/minter/ucar/dois?asset-type=software

Response:

{"minter": "UCAR", "asset-type": "software", "list": [{"doi": "10.5065/4xv0-fg55", "publisher": "UCAR/NCAR"}, {"doi": "10.5065/60hz-ry38", "publisher": "UCAR/NCAR - Earth Observing Laboratory"}, ..., {"doi": "10.5065/d6ww7g29", "publisher": "UCAR/NCAR - Unidata"}]}

  • <filter>: asset-type, publisher
  • <value>: see the list for the specific filter in the GET /citations/minter/<minter> response
Top of guide

Retrieve the list of publishers

Get the list of publishers for which citation information is being tracked.

GET /citations/publishers
$ curl https://api.rda.ucar.edu/citations/publishers

Response:

{"publishers": ["Insurance Australia Group (IAG)", "NCAR Library", ..., "University Corporation For Atmospheric Research (UCAR):National Center for Atmospheric Research (NCAR):NCAR Library (NCARLIB)", "University of Hawai\u00e2\u20ac\u02dci Department of Geography and Environment"]}

Top of guide

General options

General options are included in the query string that follows the URL for a specific operation. The query string begins with a '?' and multiple options are separated by '&'.

  • pretty-indent=X, where X is the number of spaces to indent when pretty-printing the response

    $ curl https://api.rda.ucar.edu/citations/doi/10.5065/D6M043C6?pretty-indent=4


    Response:

    {
        "doi": "10.5065/D6M043C6",
        "total_citations": 366,
        "years": {
            "min": 2014,
            "max": 2023
        }
    }

Top of guide

Errors

If an error occurs, the response will contain an error message:

{"error_message": "The specified minter \"ucarx\" is not a valid minter."}

Top of guide

Output formats

The default output format is Javascript Object Notation (JSON). You can specify a different output format by adding its extension to citations in the request URL.

Example for XML output:

GET /citations.xml/doi/10.5065/D6M043C6
$ curl https://api.rda.ucar.edu/citations.xml/doi/10.5065/D6M043C6

Available output formats and their extensions:

  • JSON: .json (default)
  • XML: .xml
Top of guide