Skip to main content

Python client for GBIF

Project description

pygbif
======

|pypi| |docs| |travis| |coverage|

Python client for the `GBIF API
<http://www.gbif.org/developer/summary>`_

`Source on GitHub at sckott/pygbif <https://github.com/sckott/pygbif>`_

Other GBIF clients:

* R: `rgbif`, `ropensci/rgbif <https://github.com/ropensci/rgbif>`_

Installation
============

Stable from pypi

.. code-block:: console

pip install pygbif

Development version

.. code-block:: console

[sudo] pip install git+git://github.com/sckott/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`

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 = LITERATURE')
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/sckott/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>`_

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/

.. |travis| image:: https://travis-ci.org/sckott/pygbif.svg
:target: https://travis-ci.org/sckott/pygbif

.. |coverage| image:: https://coveralls.io/repos/sckott/pygbif/badge.svg?branch=master&service=github
:target: https://coveralls.io/github/sckott/pygbif?branch=master


Changelog
=========

0.3.0 (2019-01-25)
------------------
- pygbif is Python 3 only now :issue:`19`
- Gains maps module with maps.map method for working with the GBIF maps API :issue:`41` :issue:`49`
- Gains new module utils with one method `wkt_rewind` :issue:`46` thanks @aubreymoore for the inspiration
- Fixed bug in registry.installations: typo in one of the parameters `identifierTyp` instead of `identifierType` :issue:`48` thanks @data-biodiversity-aq
- Link to GitHub issues from Changelog 🎉
- Fix a occurrence download test :issue:`47`
- Much more thorough docs :issue:`25`

0.2.0 (2016-10-18)
------------------
- Download methods much improved :issue:`16` :issue:`27` thanks @jlegind @stijnvanhoey @peterdesmet !
- MULTIPOLYGON now supported in `geometry` parameter :issue:`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 :issue:`39`
- Added `organizations` method to `registry` module :issue:`12`
- Added remainder of datasets methods: `registry.dataset_search` (including faceting support :issue:`37`) and `registry.dataset_suggest`, for the `/dataset/search` and `/dataset/suggest` routes, respectively :issue:`40`
- Added remainder of species methods: `species.name_lookup` (including faceting support :issue:`38`) and `species.name_usage`, for the `/species/search` and `/species` routes, respectively :issue:`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` :issue:`30` :issue:`34`
- Fixes to `**kwargs` in `occurrence.search` so that facet parameters can be parsed correctly and `requests` GET request options are collected correctly :issue:`36`
- Added `spellCheck` parameter to `occurrence.search` that goes along with the `q` parameter to optionally spell check full text searches :issue:`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 :issue:`20`
- Added more registry methods :issue:`11`
- Started occurrence download methods :issue:`16`
- Added more names methods :issue:`18`
- All requests now send user-agent headers with `requests` and `pygbif` versions :issue:`13`
- Bug fix for `occurrences.download_get` :issue:`23`
- Fixed bad example for `occurrences.get` :issue:`22`
- Fixed wheel to be universal for 2 and 3 :issue:`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


Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for pygbif, version 0.3.0
Filename, size File type Python version Upload date Hashes
Filename, size pygbif-0.3.0-py2.py3-none-any.whl (58.2 kB) File type Wheel Python version py2.py3 Upload date Hashes View hashes
Filename, size pygbif-0.3.0.tar.gz (43.3 kB) File type Source Python version None Upload date Hashes View hashes

Supported by

Elastic Elastic Search Pingdom Pingdom Monitoring Google Google BigQuery Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN SignalFx SignalFx Supporter DigiCert DigiCert EV certificate StatusPage StatusPage Status page