gbif / gbif-api

GBIF API
Apache License 2.0
27 stars 5 forks source link

Access to cited dataset DOIs in literature export #119

Open nickynicolson opened 5 months ago

nickynicolson commented 5 months ago

I'm interested in determining how many cited uses of GBIF mobilised data are to dataset DOIs, in comparison to download DOIs. The data returned from the literature export API endpoint is insufficient to answer this query. Example below compares the data available from the literature search API (1) with the tabular export endpoint (2). The former includes a reference to the dataset 10.15468/ab3s5x, not included in the latter. Users are directed to use the export through the "download as TSV" link shown on the resources page - this suggests that it will include all information used to format the data displayed on that page. Without the details for dataset level citations, this is not the case.

The contents of the tag gbifDOI from the JSON API results are shown in the tabular data column gbif_download_key when the doi represents a download (with multiple values separated by the pipe character). Can a similar column (e.g. gbif_dataset_key) be added containing the ID(s) of the referenced dataset(s) when the DOI represents a GBIF dataset? (Note - not looked closely into this, but might want to investigate similar issue with the derived dataset DOIs - see eg: https://api.gbif.org/v1/literature/21b2480f-f641-3188-980e-536f130cea01)

(1) Results from https://api.gbif.org/v1/literature/search?q=ecophysiology+green+crab

// 20240129113338
// https://api.gbif.org/v1/literature/search?q=ecophysiology+green+crab

{
  "offset": 0,
  "limit": 20,
  "endOfRecords": true,
  "count": 1,
  "results": [
    {
      "discovered": "2023-08-28",
      "authors": [
        {
          "firstName": "Markus",
          "lastName": "Frederich"
        },
        {
          "firstName": "Emily R.",
          "lastName": "Lancaster"
        }
      ],
      "countriesOfCoverage": [

      ],
      "countriesOfResearcher": [
        "US",
        "CA"
      ],
      "added": "2023-08-30T10:45:16.475+00:00",
      "published": "2024-12-31T00:00:00.000+00:00",
      "day": 31,
      "gbifDownloadKey": [

      ],
      "gbifOccurrenceKey": [
        3059035078
      ],
      "gbifTaxonKey": [
        5178595
      ],
      "gbifHigherTaxonKey": [
        1,
        229,
        54,
        2225691,
        3254253,
        637
      ],
      "gbifNetworkKey": [

      ],
      "gbifProjectIdentifier": [

      ],
      "gbifProgramme": [

      ],
      "citationType": "DOI",
      "gbifRegion": [

      ],
      "id": "c699eda6-31ef-3413-ab77-af3de0d07920",
      "identifiers": {
        "doi": "10.1016/b978-0-323-99694-5.00002-7"
      },
      "keywords": [
        "Climate change",
        "Ecological impacts",
        "Invasion history",
        "Physiological plasticity",
        "Predicted invasions",
        "Stress tolerance"
      ],
      "language": "eng",
      "literatureType": "BOOK_SECTION",
      "month": 12,
      "openAccess": false,
      "peerReview": true,
      "publisher": "Elsevier BV",
      "relevance": [
        "GBIF_CITED"
      ],
      "source": "Ecophysiology of the European Green Crab (Carcinus Maenas) and Related Species",
      "tags": [
        "2024",
        "CA",
        "GBIF_cited",
        "Invasives",
        "SDG15",
        "US",
        "citation_type:DOI",
        "gbifDOI:10.15468/ab3s5x",
        "gbifOccurrence:3059035078",
        "gbifTaxon:5178595",
        "lit_source:gs",
        "open_access:FALSE",
        "peer_review:TRUE"
      ],
      "title": "The European green crab, Carcinus maenas: Where did they come from and why are they here?",
      "topics": [
        "INVASIVES"
      ],
      "modified": "2023-08-30T10:45:16.475+00:00",
      "websites": [
        "https://doi.org/10.1016/b978-0-323-99694-5.00002-7"
      ],
      "year": 2024,
      "abstract": "Carcinus maenas is an invasive species now living on six of seven continents. Beginning slowly in the 1800s then increasing in frequency in the mid to late 1900s, the European green crab began appearing in trade ports and other areas with ship traffic, likely being transported in ballast or fouled equipment. C. maenas impacts local fisheries and ecosystems through habitat modification, competition, and aggression. In some ecosystems, invasive C. maenas acts in the food web as prey, but this has little effect on the populations of the crabs, which reproduce in great numbers year-round. Here, we discuss the invasion history and why C. maenas has been so successful. This success likely stems from multiple sources, including their reproductive strategies; body plan and size; and tolerance to extreme conditions, including salinity, hypoxia, and temperature. As extreme generalists in an ever-changing climate, C. maenas is expected to continue to outcompete native species and to invade new ecosystems, potentially even the only C. maenas-free continent, Antarctica."
    }
  ],
  "facets": [

  ]
}

(2) Tabular format record extracted from https://api.gbif.org/v1/literature/export?format=TSV

title                                                  The European green crab, Carcinus maenas: Where did they come from and why are they here?
authors                                                                                                      Markus Frederich|Emily R. Lancaster
source                                                            Ecophysiology of the European Green Crab (Carcinus Maenas) and Related Species
discovered                                                                                                                            2023-08-28
published                                                                                                               2024-12-31T00:00:00.000Z
open_access                                                                                                                                False
peer_review                                                                                                                                 True
citation_type                                                                                                                                DOI
countries_of_coverage                                                                                                                        NaN
countries_of_researcher                                                                                                     UNITED_STATES|CANADA
keywords                        Climate change|Ecological impacts|Invasion history|Physiological plasticity|Predicted invasions|Stress tolerance
literature_type                                                                                                                     BOOK_SECTION
websites                                                                                      https://doi.org/10.1016/b978-0-323-99694-5.00002-7
identifiers                                                                                                   10.1016/b978-0-323-99694-5.00002-7
id                                                                                                          c699eda6-31ef-3413-ab77-af3de0d07920
abstract                 Carcinus maenas is an invasive species now living on six of seven continents. Beginning slowly in the 1800s then inc...
topics                                                                                                                                 INVASIVES
added                                                                                                                   2023-08-30T10:45:16.475Z
gbif_download_key                                                                                                                            NaN
dnoesgaard commented 5 months ago

Hi @nickynicolson.

Thanks for raising this. While we can definitely look into improving the API and/or csv export, the general usefulness of such changes might be limited. Perhaps I can help you with a custom export to get you what you're interested in?