docs fixes & minor improvements

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
 

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

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

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:
 ########

pyobis/occurrences/occurrences.py

@@ -300,44 +300,44 @@ 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()
 
         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

pyobis/taxa/taxa.py

@@ -14,19 +14,28 @@ 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::
 
         from pyobis import taxa
 
         # 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