pygbif
|pypi| |docs| |ghactions| |coverage| |black|
Python client for the GBIF API <https://www.gbif.org/developer/summary>
_
Source on GitHub at gbif/pygbif <https://github.com/gbif/pygbif>
_
Other GBIF clients:
- R:
rgbif
, ropensci/rgbif <https://github.com/ropensci/rgbif>
_
- Ruby:
gbifrb
, sckott/gbifrb <https://github.com/sckott/gbifrb>
_
- PHP:
php-gbif
, restelae/php-gbif <https://gitlab.res-telae.cat/restelae/php-gbif>
_
Contributing: CONTRIBUTING.md <https://github.com/gbif/pygbif/blob/master/.github/CONTRIBUTING.md>
_
Installation
Stable from pypi
.. code-block:: console
pip install pygbif
Development version
.. code-block:: console
[sudo] pip install git+git://github.com/gbif/pygbif.git#egg=pygbif
pygbif
is split up into modules for each of the major groups of API methods.
- Registry - Datasets, Nodes, Installations, Networks, Organizations
- Species - Taxonomic names
- Occurrences - Occurrence data, including the download API
- Maps - Maps, get raster maps from GBIF as png or mvt
You can import the entire library, or each module individually as needed.
In addition there is a utils module, currently with one method: wkt_rewind
, and
a caching
method to manage whether HTTP requests are cached or not. See ?pygbif.caching
.
Registry module
registry module API:
organizations
nodes
networks
installations
datasets
dataset_metrics
dataset_suggest
dataset_search
Example usage:
.. code-block:: python
from pygbif import registry
registry.dataset_metrics(uuid='3f8a1297-3259-4700-91fc-acc4170b27ce')
Species module
species module API:
name_backbone
name_suggest
name_usage
name_lookup
name_parser
Example usage:
.. code-block:: python
from pygbif import species
species.name_suggest(q='Puma concolor')
Occurrences module
occurrences module API:
search
get
get_verbatim
get_fragment
count
count_basisofrecord
count_year
count_datasets
count_countries
count_schema
count_publishingcountries
download
download_meta
download_list
download_get
download_citation
download_describe
download_sql
Example usage:
.. code-block:: python
from pygbif import occurrences as occ
occ.search(taxonKey = 3329049)
occ.get(key = 252408386)
occ.count(isGeoreferenced = True)
occ.download('basisOfRecord = PRESERVED_SPECIMEN')
occ.download('taxonKey = 3119195')
occ.download('decimalLatitude > 50')
occ.download_list(user = "sckott", limit = 5)
occ.download_meta(key = "0000099-140929101555934")
occ.download_get("0000066-140928181241064")
occ.download_citation("0002526-241107131044228")
occ.download_describe("simpleCsv")
occ.download_sql("SELECT gbifid,countryCode FROM occurrence WHERE genusKey = 2435098")
Maps module
maps module API:
Example usage:
.. code-block:: python
from pygbif import maps
out = maps.map(taxonKey = 212, year = 1998, bin = "hex",
hexPerTile = 30, style = "classic-noborder.poly")
out.response
out.path
out.img
out.plot()
.. image:: https://github.com/gbif/pygbif/raw/master/gbif_map.png
:width: 25%
utils module
utils module API:
Example usage:
.. code-block:: python
from pygbif import utils
x = 'POLYGON((144.6 13.2, 144.6 13.6, 144.9 13.6, 144.9 13.2, 144.6 13.2))'
utils.wkt_rewind(x)
Contributors
Scott Chamberlain <https://github.com/sckott>
_
Robert Forkel <https://github.com/xrotwang>
_
Jan Legind <https://github.com/jlegind>
_
Stijn Van Hoey <https://github.com/stijnvanhoey>
_
Peter Desmet <https://github.com/peterdesmet>
_
Nicolas Noé <https://github.com/niconoe>
_
Meta
- License: MIT, see
LICENSE file <LICENSE>
_
- Please note that this project is released with a
Contributor Code of Conduct <CONDUCT.md>
_. By participating in this project you agree to abide by its terms.
.. |pypi| image:: https://img.shields.io/pypi/v/pygbif.svg
:target: https://pypi.python.org/pypi/pygbif
.. |docs| image:: https://readthedocs.org/projects/pygbif/badge/?version=latest
:target: http://pygbif.rtfd.org/
.. |ghactions| image:: https://github.com/gbif/pygbif/workflows/Python/badge.svg
:target: https://github.com/gbif/pygbif/actions?query=workflow%3APython
.. |coverage| image:: https://codecov.io/gh/gbif/pygbif/branch/master/graph/badge.svg?token=frXPREGk1D
:target: https://codecov.io/gh/gbif/pygbif
.. |black| image:: https://img.shields.io/badge/code%20style-black-000000.svg
:target: https://github.com/psf/black
Changelog
0.6.5 (2024-10-28)
- added support for
occurrences.download_citation
158
- added support for
occurrences.download_sql
157
- added support for
occurrences.download_describe
142
- added support for
literature.search
149
0.6.4 (2024-03-12)
- fixed a bug in building the documentation with readthedocs
138
, 129
- tests now run against live GBIF APIs
101
, 128
- updated caching.py since the
remove_expired_responses
method is deprecated. 126
0.6.3 (2023-05-25)
- added support for predicates:
isNull
, isNotNull
, in
and not
92
, 102
and 103
- added support for nested queries/dictionaries
104
- deprecated the
add_predicate
function and added add_pred_dict
to accomodate for newly supported predicates to ensure that the arguments that are sent are added in the payload function 108
- added support for multiple download formats
105
- updated operators and look-up tables
107
- included documentation on newly supported predicates and dictionaries
106
0.6.2 (2023-01-24)
- update to fix requesting GBIF downloads
- minor documentation updates
95
and 99
0.6.1 (2022-06-23)
- update to fix broken dependencies
93
- minor documentation updates
0.6.0 (2021-07-08)
- Fix for
occurrences.download
when giving geometry
as a string rather than using add_geometry
; predicates were being split on whitespace, which doesn't work for WKT 81
84
- Moved to using the
logging
module instead of print()
for giving information on occurrence download methods 78
- Clarify that
occurrences.count
for length 1 inputs only; see occurrences.search
for > 1 value 75
77
- Improved documentation for
species.name_usage
method, mostly for the language
parameter 68
- Gains download method
download_cancel
for cancelling/deleting a download request 59
0.5.0 (2020-09-29)
occurrences.search
now supports recordedByID
and identifiedByID
search parameters 62
- clean up the Contributing file, thanks @niconoe
64
- clean up internal imports in the library, thanks @niconoe
65
- fix usage of
is
and ==
, was using them inappropriately sometimes (via https://realpython.com/python-is-identity-vs-equality/), 69
- remove redundant parameter in a doc string, thanks @faroit
71
- make a test for internal fxn
gbif_GET_write
more general to avoid errors if GBIF changes content type response header slightly 72
0.4.0 (2019-11-20)
- changed base url to https for all requests; was already https for maps and downloads in previous versions
- occurrences, species, and registry modules gain docstrings with brief summary of each method
- pygbif gains ability to cache http requests. caching is off by default. See
?pygbif.caching
for all the details 52
56
via @nleguillarme
- made note in docs that if you are trying to get the same behavior as the GBIF website for name searching,
species.name_backbone
is likely what you want 55
thanks @qgroom
- for parameters that expect a
bool
, convert them to lowercase strings internally before doing HTTP requests
0.3.0 (2019-01-25)
- pygbif is Python 3 only now
19
- Gains maps module with maps.map method for working with the GBIF maps API
41
49
- Gains new module utils with one method
wkt_rewind
46
thanks @aubreymoore for the inspiration
- Fixed bug in registry.installations: typo in one of the parameters
identifierTyp
instead of identifierType
48
thanks @data-biodiversity-aq
- Link to GitHub issues from Changelog 🎉
- Fix a occurrence download test
47
- Much more thorough docs
25
0.2.0 (2016-10-18)
- Download methods much improved
16
27
thanks @jlegind @stijnvanhoey @peterdesmet !
- MULTIPOLYGON now supported in
geometry
parameter 35
- Fixed docs for
occurrences.get
, and occurrences.get_verbatim
, occurrences.get_fragment
and demo that used occurrence keys that no longer exist in GBIF 39
- Added
organizations
method to registry
module 12
- Added remainder of datasets methods:
registry.dataset_search
(including faceting support 37
) and registry.dataset_suggest
, for the /dataset/search
and /dataset/suggest
routes, respectively 40
- Added remainder of species methods:
species.name_lookup
(including faceting support 38
) and species.name_usage
, for the /species/search
and /species
routes, respectively 18
- Added more tests to cover new methods
- Changed
species.name_suggest
to give back data stucture as received from GBIF. We used to parse out the classification data, but for simplicity and speed, that is left up to the user now.
start
parameter in species.name_suggest
, occurrences.download_list
, registry.organizations
, registry.nodes
, registry.networks
, and registry.installations
, changed to offset
to match GBIF API and match usage throughout remainder of pygbif
0.1.5.4 (2016-10-01)
- Added many new
occurrence.search
parameters, including repatriated
, kingdomKey
, phylumKey
, classKey
, orderKey
, familyKey
, genusKey
, subgenusKey
, establishmentMeans
, facet
, facetMincount
, facetMultiselect
, and support for facet paging via **kwargs
30
34
- Fixes to
**kwargs
in occurrence.search
so that facet parameters can be parsed correctly and requests
GET request options are collected correctly 36
- Added
spellCheck
parameter to occurrence.search
that goes along with the q
parameter to optionally spell check full text searches 31
0.1.4 (2016-06-04)
- Added variable types throughout docs
- Changed default
limit
value to 300 for occurrences.search
method
tox
now included, via @xrotwang 20
- Added more registry methods
11
- Started occurrence download methods
16
- Added more names methods
18
- All requests now send user-agent headers with
requests
and pygbif
versions 13
- Bug fix for
occurrences.download_get
23
- Fixed bad example for
occurrences.get
22
- Fixed wheel to be universal for 2 and 3
10
- Improved documentation a lot, autodoc methods now
0.1.1 (2015-11-03)
- Fixed distribution for pypi
0.1.0 (2015-11-02)