occurrences module

class pyobis.occurrences.OccResponse(url, args, isSearch, hasMapper, isKML)[source]

An OBIS Occurrence response class

Usage

from pyobis import occurrences

query = occurrences.search(scientificname="Mola mola")
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(
    geometry="POLYGON((30.1 10.1, 10 20, 20 40, 40 40, 30.1 10.1))", size=20
)

Methods:

pyobis.occurrences.search(scientificname=None, taxonid=None, nodeid=None, datasetid=None, startdate=None, enddate=None, startdepth=None, enddepth=None, geometry=None, year=None, flags=None, fields=None, size=None, offset=0, mof=False, hasextensions=None, **kwargs)[source]

Search OBIS occurrences

Parameters:

  • taxonid – [Fixnum] An OBIS occurrence identifier

  • scientificname – [String,Array] One or more scientific names from the OBIS backbone. All included and synonym taxa are included in the search.

  • year – Removed in v3 API. [Fixnum] The 4 digit year. A year of 98 will be interpreted as AD 98. Supports range queries, smaller,larger (e.g., ‘1990,1991’, whereas ‘1991,1990’ wouldn’t work)

  • geometry – [String] Well Known Text (WKT). A WKT shape written as either POINT, LINESTRING, LINEARRING or POLYGON. Example of a polygon: ((30.1 10.1, 10 20, 20 40, 40 40, 30.1 10.1)) would be queried as https://api.obis.org/v3/occurrence?geometry=POLYGON%28%2830.1+10.1%2C+10+20%2C+20+40%2C+40+40%2C+30.1+10.1%29%29

  • nodeid – [String] Node UUID

  • taxonid – Prev. aphiaid [Fixnum] An Aphia id. This is listed as the worms_id in taxa/taxon results

  • datasetid – Prev. resourceid [Fixnum] A resource id

  • startdate – [Fixnum] Start date, formatted as YYYY-MM-DD

  • enddate – [Boolean] End date, formatted as YYYY-MM-DD

  • startdepth – [Fixnum] Start depth, in meters. Depth below sea level are treated as positive numbers.

  • enddepth – [Boolean] End depth, in meters. Depth below sea level are treated as positive numbers.

  • flags – Prev. qc [String] Quality control flags

  • fields – [String] Comma seperated list of field names. Leave blank to include all. For fetching records more than 10k, must specify ‘id’ explicitly too.

  • size – [Fixnum] Number of results to return. Default: All records

  • offset – [Fixnum] Start at record. Default: 0

  • mof – [Boolean] Include MeasurementOrFact records, true/false. Default: 0

  • hasextensions – [String] Extensions that need to be present (e.g. MeasurementOrFact, DNADerivedData).

Returns:

A dictionary

Usage:

from pyobis import occurrences
occurrences.search(scientificname = 'Mola mola').execute()

# Many names
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)

# Search on a bounding box
## in well known text format
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'],
    geometry='POLYGON((30.1 10.1, 10 20, 20 40, 40 40, 30.1 10.1))',
    size=20
).execute()
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(
    scientificname="Abra", mof=True, hasextensions="MeasurementOrFact", size=100
    ).execute()
pyobis.occurrences.get(id, **kwargs)[source]

Get an OBIS occurrence

Parameters:

id – [Fixnum] An obis occurrence identifier. It is returned in the ‘id’ field with occurrences.search().

Returns:

A dictionary

Usage:

from pyobis import occurrences
q1 = occurrences.get(id = '00003cf7-f2fc-4c53-98a6-7d846e70f5d1')
q1.execute()
q1.data # get the data
q1.api_url # get the API url
pyobis.occurrences.grid(precision, geojson=True, scientificname=None, taxonid=None, datasetid=None, nodeid=None, startdate=None, enddate=None, startdepth=None, enddepth=None, geometry=None, redlist=None, hab=None, wrims=None, event=None, flags=None, exclude=None, **kwargs)[source]

Fetch gridded occurrences as GeoJSON or KML.

Parameters:

  • precision – [integer] Geohash precision.

  • scientificname – [string] Scientific name. Leave empty to include all taxa.

  • taxonid – [string] Taxon AphiaID.

  • datasetid – [string] Dataset UUID.

  • nodeid – [string] Node UUID.

  • startdate – [string] Start date formatted as YYYY-MM-DD.

  • enddate – [string] End date formatted as YYYY-MM-DD.

  • startdepth – [integer] Start depth, in meters. Depth below sea level are treated as positive numbers.

  • enddepth – [integer] End depth, in meters. Depth below sea level are treated as positive numbers.

  • geometry – [string] Geometry, formatted as WKT or GeoHash.

  • redlist – [boolean] Red List species only, True/False.

  • hab – [boolean] HAB species only, true/false.

  • wrims – [boolean] WRiMS species only, True/False.

  • event – [string] Include pure event records (include) or get pure event records exclusively (true).

  • flags – [string] Comma separated list of required quality flags.

  • exclude – [string] Comma separated list of quality flags to be excluded.

Returns:

A dictionary

Usage:

from pyobis import occurrences

occurrences.grid(100, True) // returns in GeoJSON format
ococcurrences.grid(1000, False)   // returns in KML format
pyobis.occurrences.getpoints(scientificname=None, taxonid=None, datasetid=None, nodeid=None, startdate=None, enddate=None, startdepth=None, enddepth=None, geometry=None, redlist=None, hab=None, wrims=None, event=None, flags=None, exclude=None, **kwargs)[source]

Fetch point occurrences as GeoJSON (aggregated to Geohash precision 8).

Parameters:

  • scientificname – [string] Scientific name. Leave empty to include all taxa.

  • taxonid – [string] Taxon AphiaID.

  • datasetid – [string] Dataset UUID.

  • nodeid – [string] Node UUID.

  • startdate – [string] Start date formatted as YYYY-MM-DD.

  • enddate – [string] End date formatted as YYYY-MM-DD.

  • startdepth – [integer] Start depth, in meters. Depth below sea level are treated as positive numbers.

  • enddepth – [integer] End depth, in meters. Depth below sea level are treated as positive numbers.

  • geometry – [string] Geometry, formatted as WKT or GeoHash.

  • redlist – [boolean] Red List species only, True/False.

  • hab – [boolean] HAB species only, true/false.

  • wrims – [boolean] WRiMS species only, True/False.

  • event – [string] Include pure event records (include) or get pure0 event records exclusively (true).

  • flags – [string] Comma separated list of quality flags which need to be set.

  • exclude – [string] Comma separated list of quality flags to be excluded.

Returns:

A dictionary

Usage:

from pyobis import occurrences
occurrences.getpoints(scientificname = 'Mola mola')

## Many names
occurrences.getpoints(scientificname = ['Mola mola','Abra alba'])
pyobis.occurrences.point(x, y, z=None, scientificname=None, taxonid=None, datasetid=None, nodeid=None, startdate=None, enddate=None, startdepth=None, enddepth=None, geometry=None, redlist=None, hab=None, wrims=None, event=None, flags=None, exclude=None, **kwargs)[source]

Fetch point occurrences for a location (with Geohash precision 8 or variable Geohash precision) as GeoJSON.

Parameters:

  • x – [float] latitudes of a location

  • y – [float] longitude of a location

  • z – [float] vertical datum (geodatic datum WGS84)

  • scientificname – [string] Scientific name. Leave empty to include all taxa.

  • taxonid – [string] Taxon AphiaID.

  • datasetid – [string] Dataset UUID.

  • nodeid – [string] Node UUID.

  • startdate – [string] Start date formatted as YYYY-MM-DD.

  • enddate – [string] End date formatted as YYYY-MM-DD.

  • startdepth – [integer] Start depth, in meters. Depth below sea level are treated as positive numbers.

  • enddepth – [integer] End depth, in meters. Depth below sea level are treated as positive numbers.

  • geometry – [string] Geometry, formatted as WKT or GeoHash.

  • redlist – [boolean] Red List species only, True/False.

  • hab – [boolean] HAB species only, true/false.

  • wrims – [boolean] WRiMS species only, True/False.

  • event – [string] Include pure event records (include) or get pure event records exclusively (true).

  • flags – [string] Comma separated list of quality flags which need to be set.

  • exclude – [string] Comma separated list of quality flags to be excluded.

Returns:

A dictionary

Usage:

from pyobis import occurrences
occurrences.point(x=1.77,y=54.22,scientificname = 'Mola mola')
pyobis.occurrences.tile(x, y, z, mvt=0, scientificname=None, taxonid=None, datasetid=None, nodeid=None, startdate=None, enddate=None, startdepth=None, enddepth=None, geometry=None, redlist=None, hab=None, wrims=None, event=None, flags=None, exclude=None, **kwargs)[source]

Fetch point occurrences for a tile (aggregated using variable Geohash precision based on zoom level) as GeoJSON or MVT.

Parameters:

  • x – [float] latitudes of a location

  • y – [float] longitude of a location

  • z – [float] vertical datum (geodatic datum WGS84)

  • scientificname – [string] Scientific name. Leave empty to include all taxa.

  • taxonid – [string] Taxon AphiaID.

  • datasetid – [string] Dataset UUID.

  • nodeid – [string] Node UUID.

  • startdate – [string] Start date formatted as YYYY-MM-DD.

  • enddate – [string] End date formatted as YYYY-MM-DD.

  • startdepth – [integer] Start depth, in meters. Depth below sea level are treated as positive numbers.

  • enddepth – [integer] End depth, in meters. Depth below sea level are treated as positive numbers.

  • geometry – [string] Geometry, formatted as WKT or GeoHash.

  • redlist – [boolean] Red List species only, True/False.

  • hab – [boolean] HAB species only, true/false.

  • wrims – [boolean] WRiMS species only, True/False.

  • event – [string] Include pure event records (include) or get pure event records exclusively (true).

  • flags – [string] Comma separated list of quality flags which need to be set.

  • exclude – [string] Comma separated list of quality flags to be excluded.

Returns:

A dictionary

Usage:

from pyobis import occurrences
occurrences.tile(x=1.77,y=52.26,z=0.5,mvt=0, scientificname = 'Mola mola')
occurrences.tile(x=1.77,y=52.26,z=0.5,mvt=1, scientificname = 'Mola mola')
pyobis.occurrences.centroid(scientificname=None, taxonid=None, datasetid=None, nodeid=None, startdate=None, enddate=None, startdepth=None, enddepth=None, geometry=None, redlist=None, hab=None, wrims=None, event=None, flags=None, exclude=None, **kwargs)[source]

Determine the centroid for a selection of occurrence records.

Parameters:

  • scientificname – [string] Scientific name. Leave empty to include all taxa.

  • taxonid – [string] Taxon AphiaID.

  • datasetid – [string] Dataset UUID.

  • nodeid – [string] Node UUID.

  • startdate – [string] Start date formatted as YYYY-MM-DD.

  • enddate – [string] End date formatted as YYYY-MM-DD.

  • startdepth – [integer] Start depth, in meters. Depth below sea level are treated as positive numbers.

  • enddepth – [integer] End depth, in meters. Depth below sea level are treated as positive numbers.

  • geometry – [string] Geometry, formatted as WKT or GeoHash.

  • redlist – [boolean] Red List species only, True/False.

  • hab – [boolean] HAB species only, true/false.

  • wrims – [boolean] WRiMS species only, True/False.

  • event – [string] Include pure event records (include) or get pure event records exclusively (true).

  • flags – [string] Comma separated list of required quality flags.

  • exclude – [string] Comma separated list of quality flags to be excluded.

Returns:

A dictionary

Usage:

from pyobis import occurrences
occurrences.centroid(scientificname = 'Mola mola')
pyobis.occurrences.lookup_taxon(scientificname)[source]

Lookup for taxon metadata with scientificname

Parameters:

scientificname – [String] Scientific Name

Returns:

A dictionary of taxon metadata for the best matches to the input

Usage:

from pyobis import occurrences
lookup_data = occurrences.lookup_taxon(scientificname="Mola mola")
print(lookup_data)