skip to navigation
skip to content

idigbio 0.8.4

Python Client for the iDigBio Search API

A python client for the iDigBio iDigBio v2 API.


pip install idigbio

If you want to use the Pandas Data Frame interface you need to install pandas as well.

pip install idigbio pandas

Basic Usage

Returning JSON from the API.

import idigbio
api = idigbio.json()
json_output = api.search_records()

Returning a Pandas Data Frame.

import idigbio
api = idigbio.pandas()
pandas_output = api.search_records()

See the Search API docs for info about the endpoint parameters.


View a Record By UUID

import idigbio
api = idigbio.json()
record = api.view("records","1db58713-1c7f-4838-802d-be784e444c4a")

Search for a Record by scientific name

import idigbio
api = idigbio.json()
record_list = api.search_records(rq={"scientificname": "puma concolor"})

Search for Records that have images

import idigbio
api = idigbio.json()
record_list = api.search_records(rq={"scientificname": "puma concolor", "hasImage": True})

Search for a MediaRecords by record property

import idigbio
api = idigbio.json()
mediarecord_list = api.search_media(rq={"scientificname": "puma concolor", "hasImage": True})

Create a heat map for a genus

import idigbio
api = idigbio.json()
m = api.create_map(rq={"genus": "acer"}, t="geohash")
m.save_map_image("acer_map_geohash", 2)

Create a point map for a genus

import idigbio
api = idigbio.json()
m = api.create_map(rq={"genus": "acer"}, t="points")
m.save_map_image("acer_map_points", 2)

Create a zoomed in point map for a bounding box

import idigbio
api = idigbio.json()
bbox = {"type": "geo_bounding_box", "bottom_right": {"lat": 29.642979999999998, "lon": -82.00}, "top_left": {"lat": 29.66298, "lon": -82.35315800000001}}
m = api.create_map(
    rq={"geopoint": bbox}
m.save_map_image("test.png", None, bbox=bbox)

Create a summary of kingdom and phylum data

import idigbio
api = idigbio.json()
summary_data = api.top_records(fields=["kingdom", "phylum"])

Get the number of Records for a search by scientific name

import idigbio
api = idigbio.json()
count = api.count_records(rq={"scientificname": "puma concolor"})

Get the number of MediaRecords for a search by scientific name

import idigbio
api = idigbio.json()
count = api.count_media(rq={"scientificname": "puma concolor"})

Get the histogram of Collection Dates for a search by record property, for the last 10 years

import idigbio
api = idigbio.json()
histogram_data = api.datehist(
    rq={"scientificname": "puma concolor"},
    top_fields=["institutioncode"], min_date="2005-01-01")


To contribute code to this project, please submit a pull request to the repo on github:

To set up a development environment, run the following from inside a python virtual environment in your local repo directory:

pip install -e .

Release History

0.8.4 (2017-06-07)


  • added full-featured example script to download media from iDigBio
  • added documentation for fetch_media


  • removed which is superceded by (2017-05-17)


  • add an example to examples directory to download media based on search query


  • minor changes to documentation, unit tests
  • remove hard-coded path to tmp directory

0.8.2 (2017-05-10)


  • count_recordsets() function returns number of recordsets in iDigBio

0.8.1 (2016-08-29)

  • Send etag with file on upload to verify correctness

0.6.1 (2016-04-08)


  • Add media_type to upload functionality.

0.6.0 (2016-03-30)


  • Make pandas an extra requirements, update docs


  • Specify auth for api backend
  • Upload image capability (requires auth)

0.5.0 (2016-02-24)


  • Don’t exclude data.* fields if requested specifically
  • Fix stats and datehist api calls to respect parameters; param names changed to use python style and match server params.

0.4.3 (2016-02-23)


  • no results no longer errs in the pandas client.
  • limit correctly limits to specified record, not next larger batch size


  • Clarify targetted python versions
File Type Py Version Uploaded on Size
idigbio-0.8.4.tar.gz (md5) Source 2017-06-07 8KB