diff --git a/README.md b/README.md index f1045009..a3e81442 100644 --- a/README.md +++ b/README.md @@ -2,7 +2,7 @@ [![pypi](https://img.shields.io/pypi/v/pyobis.svg)](https://pypi.python.org/pypi/pyobis) [![Conda Version](https://img.shields.io/conda/vn/conda-forge/pyobis.svg)](https://anaconda.org/conda-forge/pyobis) -[![docs](https://github.com/iobis/pyobis/actions/workflows/deploy-docs.yml/badge.svg)](https://iobis.github.ic/pyobis) +[![docs](https://github.com/iobis/pyobis/actions/workflows/deploy-docs.yml/badge.svg)](https://iobis.github.io/pyobis) [![tests](https://github.com/iobis/pyobis/actions/workflows/tests.yml/badge.svg)](https://github.com/iobis/pyobis/actions/workflows/tests.yml) Python client for the [OBIS API](https://api.obis.org/). @@ -69,7 +69,7 @@ data = query.execute() ## Documentation -For more information, see the [documentation](https://pyobis.readthedocs.io/). +For more information, see the [documentation](https://iobis.github.io/pyobis). ## License diff --git a/docs/index.rst b/docs/index.rst index 9c9a2a6b..e95425cd 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -101,7 +101,7 @@ Nodes module from pyobis import nodes - query = nodes.search(scientificname=["Mola", "Abra"], cache=True) + query = nodes.search(id="4bf79a01-65a9-4db6-b37b-18434f26ddfc", cache=True) query.execute() query.data # Returns the data query.api_url # Returns the API URL diff --git a/docs/nodes.rst b/docs/nodes.rst index b84e86d6..860f9c90 100644 --- a/docs/nodes.rst +++ b/docs/nodes.rst @@ -14,7 +14,7 @@ Usage from pyobis import nodes - query = nodes.search(scientificname=["Mola", "Abra"], cache=True, **kwargs) + query = nodes.search(id="4bf79a01-65a9-4db6-b37b-18434f26ddfc", cache=True) query.execute() query.data # Returns the data query.api_url # Returns the API URL diff --git a/docs/occurrences.rst b/docs/occurrences.rst index 150683bf..6ad1c5d2 100644 --- a/docs/occurrences.rst +++ b/docs/occurrences.rst @@ -14,16 +14,20 @@ Usage from pyobis import occurrences + # Use the Query Builder query = occurrences.search(scientificname="Mola mola", cache=True) query.execute() query.data # Returns the data query.api_url # Returns the OBIS API URL query.mapper_url # Returns the OBIS Mapper URL - data = occurrences.search(scientificname="Mola mola", size=10).execute() - occurrences.search( + # Maximally simple example: + data = occurrences.search(scientificname="Mola mola").execute() + + # Another example with a bounding box and size limit. + data = occurrences.search( geometry="POLYGON((30.1 10.1, 10 20, 20 40, 40 40, 30.1 10.1))", size=20 - ) + ).execute() Methods: ######## diff --git a/pyobis/occurrences/occurrences.py b/pyobis/occurrences/occurrences.py index 50cc1628..ef2f96fe 100644 --- a/pyobis/occurrences/occurrences.py +++ b/pyobis/occurrences/occurrences.py @@ -300,24 +300,24 @@ def search( :param hasextensions: [String] Extensions that need to be present (e.g. MeasurementOrFact, DNADerivedData). :param cache: [bool, optional] Whether to use caching. Defaults to True. - :return: A dictionary + :return: OccResponse which can be turned into a pandas dataframe of taxon occurrences using .execute(). Usage:: from pyobis import occurrences - occurrences.search(scientificname = 'Mola mola').execute() + df = occurrences.search(scientificname = 'Mola mola').execute() # Many names - occurrences.search(scientificname = ['Mola', 'Abra', 'Lanice', 'Pectinaria']).execute() + df = occurrences.search(scientificname = ['Mola', 'Abra', 'Lanice', 'Pectinaria']).execute() # Use paging parameters (limit and start) to page. # Note the different results for the two queries below. - occ.search(scientificname = 'Mola mola', offset=0, size=10) - occ.search(scientificname = 'Mola mola', offset=10, size=10) + df = occ.search(scientificname = 'Mola mola', offset=0, size=10) + df = occ.search(scientificname = 'Mola mola', offset=10, size=10) # Search on a bounding box ## in well known text format - occurrences.search( + df = occurrences.search( geometry='POLYGON((30.1 10.1, 10 20, 20 40, 40 40, 30.1 10.1))', size=20 ).execute() @@ -325,19 +325,19 @@ def search( from pyobis import taxa res = taxa.search(scientificname='Mola mola').execute()['results'][0] - occurrences.search( - obisid=res['id'], + df = occurrences.search( + obisid=res['taxonID'], geometry='POLYGON((30.1 10.1, 10 20, 20 40, 40 40, 30.1 10.1))', size=20 ).execute() - occurrences.search( + df = occurrences.search( aphiaid=res['worms_id'], geometry='POLYGON((30.1 10.1, 10 20, 20 40, 40 40, 30.1 10.1))', size=20 ).execute() # Get mof response as a pandas dataframe - occurrences.search( + df = occurrences.search( scientificname="Abra", mof=True, hasextensions="MeasurementOrFact", size=100 ).execute() """ # noqa: E501 diff --git a/pyobis/taxa/taxa.py b/pyobis/taxa/taxa.py index 0a3408b9..a61042a3 100644 --- a/pyobis/taxa/taxa.py +++ b/pyobis/taxa/taxa.py @@ -14,7 +14,14 @@ def search(scientificname=None, cache=True, **kwargs): :param scientificname: [String,Array] One or more scientific names from the OBIS backbone. All included and synonym taxa are included in the search :param cache: [bool, optional] Whether to use caching. Defaults to True. - :return: A dictionary + :return: Dictionary with keys: [ + 'scientificName', 'scientificNameAuthorship', 'taxonID', 'ncbi_id', + 'taxonRank', 'taxonomicStatus', 'acceptedNameUsage', + 'acceptedNameUsageID', 'is_marine', 'kingdom', 'phylum', 'subphylum', + 'superclass', 'class', 'subclass', 'superorder', 'order', 'kingdomid', + 'phylumid', 'subphylumid', 'superclassid', 'classid', 'subclassid', + 'superorderid', 'orderid', 'vernacularNames' + ] Usage:: @@ -22,11 +29,13 @@ def search(scientificname=None, cache=True, **kwargs): # With caching enabled (default) query = taxa.search(scientificname='Mola mola') - query.execute() - + result = query.execute() + aphia_id = result['results'][0]['taxonID'] + # With caching disabled query = taxa.search(scientificname='Mola mola', cache=False) - query.execute() + result = query.execute() + aphia_id = result['results'][0]['taxonID'] # Get the data query.data # return the fetched data