pygbif 0.6.3

Python client for GBIF

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

registry 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`

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")

Maps module
===========

maps module API:

* `map`

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%
:scale: 25%

utils module
============

utils module API:

* `wkt_rewind`

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.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)
------------------
- First release