Metadata-Version: 2.0
Name: idigbio
Version: 0.8.0
Summary: Python Client for the iDigBio Search API
Home-page: http://github.com/idigbio/idigbio-python-client/
Author: Alex Thompson
Author-email: godfoder@acis.ufl.edu
License: MIT
Platform: UNKNOWN
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Natural Language :: English
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 2.7
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.3
Classifier: Programming Language :: Python :: 3.4
Classifier: Programming Language :: Python :: 3.5
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Dist: requests
Provides-Extra: pandas
Requires-Dist: pandas; extra == 'pandas'

idigbio-python-client
=====================

.. image:: https://img.shields.io/pypi/v/idigbio.svg
    :target: https://pypi.python.org/pypi/idigbio

.. image:: https://img.shields.io/travis/iDigBio/idigbio-python-client.svg
        :target: https://travis-ci.org/iDigBio/idigbio-python-client

A python client for the `iDigBio <https://www.idigbio.org/>`_ iDigBio v2 API.

Installation
------------

.. code-block::

    pip install idigbio

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

.. code-block::

    pip install idigbio pandas

Basic Usage
-----------

Returning JSON from the API.

.. code-block:: python

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

Returning a Pandas Data Frame.

.. code-block:: python

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

See the `Search API docs
<https://github.com/idigbio/idigbio-search-api/wiki>`_ for info about
the endpoint parameters.


Examples
++++++++

View a Record By UUID

.. code-block:: python

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

Search for a Record by scientific name

.. code-block:: python

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

Search for Records that have images

.. code-block:: python

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

Search for a MediaRecords by record property

.. code-block:: python

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

Create a heat map for a genus

.. code-block:: python

    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

.. code-block:: python

    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

.. code-block:: python

    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

.. code-block:: python

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

Get the number of Records for a search by scientific name

.. code-block:: python

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

Get the number of MediaRecords for a search by scientific name

.. code-block:: python

    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

.. code-block:: python

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


.. :changelog:

Release History
---------------

0.6.1 (2016-04-08)
++++++++++++++++++

** Changes **

- Add media_type to upload functionality.

0.6.0 (2016-03-30)
++++++++++++++++++

**Changes**

- Make pandas an extra requirements, update docs

**New**

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



0.5.0 (2016-02-24)
++++++++++++++++++

**Changes**

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

**Bugfixes**

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

**Miscellaneous**

- Clarify targetted python versions


