Get a citation from a GBIF download key #60 (#156)

pygbif/gbifutils.py

@@ -35,6 +35,9 @@ def gbif_GET(url, args, **kwargs):
     stopifnot(out.headers["content-type"])
     return out.json()
 
+def gbif_GET_raw(url):
+    out = requests.get(url)
+    return out.content
 
 def gbif_GET_map(url, args, ctype, **kwargs):
     out = requests.get(url, params=args, headers=make_ua(), **kwargs)

pygbif/occurrences/__init__.py

@@ -17,6 +17,7 @@
 * `download_list`: Lists the downloads created by a user
 * `download_get`: Get a download from GBIF
 * `download_cancel`: Cancel a download from GBIF
+* `citation`: Get citation from a download key
 """
 
 from .search import search
@@ -37,3 +38,4 @@
     download_get,
     download_cancel,
 )
+from .citation import citation

pygbif/occurrences/citation.py

@@ -0,0 +1,24 @@
+from pygbif.gbifutils import gbif_baseurl, gbif_GET_raw
+import re
+
+def citation(key):
+    """
+    Get citation from a download key
+
+    :param key: [int] A GBIF download key
+
+    :return: A dictionary, of results
+
+    Usage::
+
+        from pygbif import occurrences
+        occurrences.citation("0235283-220831081235567")
+
+    """
+    url = gbif_baseurl + "occurrence/download/" + str(key) + "/citation"
+    if re.fullmatch(r'^\d+-\d+$', key):
+        out = gbif_GET_raw(url).decode('utf-8')
+        return(out)
+    else:
+        raise ValueError("key must be a GBIF download key")
+

test/test-occurrences-citation.py

@@ -0,0 +1,15 @@
+from pygbif import occurrences
+import vcr
+
+@vcr.use_cassette('test/vcr_cassettes/test-occurrences-citation.yaml')
+def test_citation():
+    res=occurrences.citation("0235283-220831081235567")
+    assert "str" == res.__class__.__name__
+    "GBIF.org (2 January 2023) GBIF Occurrence Download https://doi.org/10.15468/dl.29wbtx" == res 
+
+def test_citation_fails_well():
+    try:
+        occurrences.citation("dog")
+    except ValueError as e:
+        assert str(e) == "key must be a GBIF download key"
+

test/vcr_cassettes/test-occurrences-citation.yaml

@@ -0,0 +1,54 @@
+interactions:
+- request:
+    body: null
+    headers:
+      Accept:
+      - '*/*'
+      Accept-Encoding:
+      - gzip, deflate
+      Connection:
+      - keep-alive
+      User-Agent:
+      - python-requests/2.32.3
+    method: GET
+    uri: https://api.gbif.org/v1/occurrence/download/0235283-220831081235567/citation
+  response:
+    body:
+      string: 'GBIF.org (2 January 2023) GBIF Occurrence Download https://doi.org/10.15468/dl.29wbtx
+
+        '
+    headers:
+      Accept-Ranges:
+      - bytes
+      Age:
+      - '1789'
+      Cache-Control:
+      - public, max-age=3603
+      Connection:
+      - keep-alive
+      Content-Length:
+      - '86'
+      Content-Type:
+      - application/json
+      Date:
+      - Wed, 02 Oct 2024 08:19:22 GMT
+      Expires:
+      - '0'
+      Pragma:
+      - no-cache
+      Vary:
+      - Origin, Access-Control-Request-Method, Access-Control-Request-Headers
+      Via:
+      - 1.1 varnish (Varnish/6.0)
+      X-Content-Type-Options:
+      - nosniff
+      X-Frame-Options:
+      - DENY
+      X-Varnish:
+      - 537231613 407639130
+      X-XSS-Protection:
+      - 1; mode=block
+    status:
+      code: 200
+      message: OK
+version: 1