Open API to get metadata, geographic plots, and statitics from bio-database, ODB, Institute of Oceanography, NTU, Taiwan.
The API is in development stage and documentation is under construction. Updates will be continued. Now the bioquery API have following functions

bioquery
geo2map
geo2wwwmap
txt2geojson
site_intersect

The APIs are RESTful that can be accesssed by using cURL commands. The following sections provide examples. Basically, ‘bioquery’ is the unified one that will call other functions by specifying its argument ‘return_type’ (see details about return_type).
A GUI client is provided in https://bio.odb.ntu.edu.tw/query integrated with BioQuery Map. Just query ODB bio-data and try these APIs interactively online.

Open API.01

POST

keyword: bioquery site2map

API cURL url: https://bio.odb.ntu.edu.tw/api/bioquery/png {pdf, svg}

site2map can plot sites, polygons, and overlay of environmental layer.
Basically it calls geo2map API, and can be incorporated with query criteria from BioQuery web applications in bio.odb.ntu.edu.tw/query

Body

formdata

config	Query crieteria downloaded from BioQuery: bio.odb.ntu.edu.tw/query, or a config text, json, or yaml file.
return_type	“site2map” return data type, here, “site2map” can return png, svg, or pdf
legend_pos	“bottom” Optional. Legend positon: “none” (no legend) “bottomright”, “topleft”, “right”, “bottom”, and so on

cURL

Example Request: bioquery site2map

curl --location --request POST "https://bio.odb.ntu.edu.tw/api/bioquery/png" \
  --form "config=@Your_File_Path" \
  --form "return_type=\"site2map\"" \
  --form "legend_pos=\"bottom\"" -o output.png

Response

Bioquery site2map with polygonal region

Open API.02

POST

keyword: bioquery upload user data

API cURL url: https://bio.odb.ntu.edu.tw/api/bioquery/png {pdf, svg}

Users can upload community abundance data of species assemblages, which can be combined with ODB data (by ‘config’ parameter). This combined data then can be used in various statistics or plotting according to ‘return_type’ parameter. Data format and rules of combination see: https://bio.odb.ntu.edu.tw/query/?help=user_data

Body

formdata

config	Query crieteria from bio.odb.ntu.edu.tw/query, or a config text, json, or yaml file.
return_type	“site2map” return data type, here, “site2map” can return png, svg, or pdf
datasrc	Abundance data csv file of species assemblages. Data format see: https://bio.odb.ntu.edu.tw/query/?help=user_data
data_mode	“combine” Specify how user data combined with ODB data (from config): “indep”, “combine”, “combine_region” or “site”. Details see: https://bio.odb.ntu.edu.tw/query/?help=user_data
data_id	“taxon” Specify the variable name in datasrc which means species identification (default: “taxon”)
data_val	“taxon_count” Specify the variable name in datasrc which means species abundance or occurrence (default: “taxon_count”)
data_group	“polyID” Specify the grouping variable name in datasrc (default: “polyID”, polygonal region ID in integer)
geopoly	Optional. Can be file specified longitude and latitude of polygonal regions with id, as format “csv_poly” in this example, or a character vector contains geometry text with format “lonlat_poly”, bounding box with format “BBOX” (see next example), or BioQuery downloaded query text file with format “bioquery”.
format	“csv_poly” Optional but needed if specify geopoly: “csv” (CSV file with coordinates in geopoly parameter), “csv_poly” (CSV wity column of polygonal ID), “bioquery” (Config file downloaded from BioQuery: bio.odb.ntu.edu.tw/query), “bbox” (bounding box), “lonlat_poly” (string format in geopoly parameter to specify polygonal region, such as geopoly=“(124,125,124.5,124,20,21,22,20);(120,121,122,122.5,120,19,20,22,22,19)”), “kml” (KML file).
grd_sel	1 Optional. Specify grid for data gridding: null (raw data), 0 (0.25-deg), 1 (0.5-deg, default), 2 (1-deg)
include_poly0	false Optional. Enable analysis including polyID==0, i.e., also analysis those sites which are outside the given polygonal regions (default: FALSE).

cURL

Example Request: bioquery upload user data

curl --location --request POST "https://bio.odb.ntu.edu.tw/api/bioquery/png" \
  --form "config=@Your_File_Path" \
  --form "return_type=\"site2map\"" \
  --form "datasrc=@Your_File_Path" \
  --form "data_mode=\"combine\"" \
  --form "data_id=\"taxon\"" \
  --form "data_val=\"taxon_count\"" \
  --form "data_group=\"polyID\"" \
  --form "geopoly=@Your_File_Path" \
  --form "format=\"csv_poly\"" \
  --form "grd_sel=1" \
  --form "include_poly0=false" -o output.png

Response

User data combined with ODB data with regions respectively

Open API.03

POST

keyword: bioquery overlay environmental layer

API cURL url: https://bio.odb.ntu.edu.tw/api/bioquery/png {pdf, svg}

Environmental (Env) factors can be specified or uploaded and used in succeeding analysis. Specify ‘envsrc’ which means various sources of env databases compiled by ODB, and ‘env_layer’, i.e., the env factors contained in this source. Each env-layer can be applied with spatially kriging, transformed, and scaled. Details see: https://bio.odb.ntu.edu.tw/query/?help=bioenv

Body

formdata

config	Query crieteria from bio.odb.ntu.edu.tw/query, or a config text, json, or yaml file.
return_type	“site2map” return data type, here, “site2map” can return png, svg, or pdf
env_layer	“chl” Environmental layer name that used in the specified “envsrc”. See BioQuery: bio.odb.ntu.edu.tw/query to find all options for env_layer.
envsrc	“nasa_neo” Environmental source, either a file with longitude/latitude/(season)/env_layer, or a env database provided (or compiled) by ODB, NTU. Here “nasa_neo” means NASA NEO env data, and we fetch SST data. See BioQuery: bio.odb.ntu.edu.tw/query to find all options for envsrc.
by_season	true Optional. Plot with seasonality facets, if “season” in specified “envsrc”. (default is true)
scale_res	“large” Optional. Coastline resolution: “small”, “medium”, “large”
getenv_options	‘{"en_trans":["1"], "scale_fun":["log"], "scale_mul":["1000"], "en_kriging":["0"]}’ Optional. Json string that specify env_layer need transformation (en_trans: 1/0) by multipling a factor (scal_mul), by functions (scale_fun: “log”, “sqrt”, “exp”,…), or kriging (en_kriging: 1/0). Note: kriging is time-consuming
geopoly	“BBOX (110,15,130,35)” Optional. Plot map within a bounding box
format	“bbox” Optional but needed if specify geopoly: “csv” (CSV file with coordinates in geopoly parameter), “csv_poly” (CSV wity column of polygonal ID), “bioquery” (Config file downloaded from BioQuery: bio.odb.ntu.edu.tw/query), “bbox” (bounding box), “lonlat_poly” (string format in geopoly parameter to specify polygonal region, such as geopoly=“(124,125,124.5,124,20,21,22,20);(120,121,122,122.5,120,19,20,22,22,19)”), “kml” (KML file).
en_poly_border	false Optional. Plot outlines of polygonal region or not.
enlarge_poly_bbox	false Optional. Enlarge plotting content to include bounding box inside.

cURL

Example Request: bioquery overlay environmental layer

curl --location --request POST "https://bio.odb.ntu.edu.tw/api/bioquery/png" \
  --form "return_type=\"site2map\"" \
  --form "env_layer=\"chl\"" \
  --form "envsrc=\"nasa_neo\"" \
  --form "by_season=true" \
  --form "scale_res=\"large\"" \
  --form "getenv_options='{\"en_trans\":[\"1\"], \"scale_fun\":[\"log\"], \"scale_mul\":[\"1000\"], \"en_kriging\":[\"0\"]}'" \
  --form "geopoly=\"BBOX (110,15,130,35)\"" \
  --form "format=\"bbox\"" \
  --form "en_poly_border=false" \
  --form "enlarge_poly_bbox=false" -o output.png

Response

SST, or other env layer overlay on map with seasonality

Open API.04

POST

keyword: bioquery estimate species diversity

API cURL url: https://bio.odb.ntu.edu.tw/api/bioquery/json {png, pdf, svg}

For the uploaded data (by ‘datasrc’) or ODB data (by ‘config’), species diversity can be estimated by using iNEXT method. The computation is time-consuming depends on your data amount and complexity, which may hang up upon slow network. A predicted diversity either shown as rarefaction curves or as a table of species diversity estimation by specifying ‘return_type’. Details see: https://bio.odb.ntu.edu.tw/query/?help=div_eval

Body

formdata

config	Query crieteria from bio.odb.ntu.edu.tw/query, or a config text, json, or yaml file.
return_type	“estimate_diversity_by_coverage” return data type, here, “estimate_diversity_by_coverage” can return table of species diversity estimation by sample coverage, similar as “estimate_diversity_by_samplesize”. By specifying ‘rarefaction_plot’ and using ‘png/svg/pdf’ in endpoint of API, return rarefation curves.
grd_sel	1 Optional. Specify grid for data gridding: null (raw data), 0 (0.25-deg), 1 (0.5-deg, default), 2 (1-deg)
by_season	true Optional. Subdivide results into seasonality (0-3 from spring to winter, respectively).

cURL

Example Request: bioquery estimate species diversity

curl --location --request POST "https://bio.odb.ntu.edu.tw/api/bioquery/json" \
  --form "config=@Your_File_Path" \
  --form "return_type=\"estimate_diversity_by_coverage\"" \
  --form "grd_sel=1" \
  --form "by_season=true" -o output.json

Response

Example Response Table

[   
  {   
    "longitude": 121,   
    "latitude": 21.5,   
    "season": 0,   
    "InPoly": 1,   
    "Estimator": 63.45,   
    "LCL": 62.432,   
    "UCL": 64.468,   
    "std_err": 0.5194,   
  },       
  { ... }      
]

Rarefaction curves of Hill N1 diversity in each grid for seasons

Open API.05

POST

keyword: bioquery environment pair-correlation

API cURL url: https://bio.odb.ntu.edu.tw/api/bioquery/png {pdf, svg}

API to evaluate (and plot) pair correlation of community abundance and species diversity of each grid with longitude, latitude, and various environmental factors. Details see: https://bio.odb.ntu.edu.tw/query/?help=corr_plot

Body

formdata

config	Query crieteria from bio.odb.ntu.edu.tw/query, or a config text, json, or yaml file.
return_type	“abundance_corrplot” return data type, here, “abundance_corrplot” correlates community abundance data with specified env layers. Correlates both species diversity and abundance with env by using ‘community_stats_corrplot’, but note that it’s time-consuming when evaluating diversity.
env_layer	‘["depth","chl","nitrate"]’ Environmental layer name that used in the specified “envsrc”. See BioQuery: bio.odb.ntu.edu.tw/query to find all options for env_layer. Specify multiple env layers by using json string, or equivalently in cURL, using curl -F “env_layer=["depth","chl","nitrate"]”.
envsrc	‘["depth","nasa_neo","noaa_wod"]’ Envsrc is either a file with longitude/latitude/(season)/env_layer, or a env database provided (or compiled) by ODB, NTU. See BioQuery: bio.odb.ntu.edu.tw/query to find all options for envsrc. Specify multiple env sources, respectively, by using json string, or equivalently in cURL, using curl -F “envsrc= ["depth","nasa_neo","noaa_wod"]”.
getenv_options	‘{"en_trans":["0","1","1"], "scale_fun":["c","log","log"], "scale_mul":["1","1000","1000"], "en_kriging":["0","0","1"]}’ Optional. Json string that specify env_layer need transformation (en_trans: 1/0) by multipling a factor (scal_mul), by functions (scale_fun: “log”, “sqrt”, “exp”,…), or kriging (en_kriging: 1/0). Note: kriging is time-consuming

cURL

Example Request: bioquery environment pair-correlation

curl --location --request POST "https://bio.odb.ntu.edu.tw/api/bioquery/png" \
  --form "config=@Your_File_Path" \
  --form "return_type=\"abundance_corrplot\"" \
  --form "env_layer='[\"depth\",\"chl\",\"nitrate\"]'" \
  --form "envsrc='[\"depth\",\"nasa_neo\",\"noaa_wod\"]'" \
  --form "getenv_options='{\"en_trans\":[\"0\",\"1\",\"1\"], \"scale_fun\":[\"c\",\"log\",\"log\"], \"scale_mul\":[\"1\",\"1000\",\"1000\"], \"en_kriging\":[\"0\",\"0\",\"1\"]}'" -o output.png

Response

Pair correlation of community abundance with environmental factors

Open API.06

POST

keyword: bioquery RDA ordination

API cURL url: https://bio.odb.ntu.edu.tw/api/bioquery/png {pdf, svg}

API to evaluate Redundancy Analysis (RDA) and get ordination plot or related statitics for site scores, species scores, and environmental factors fitted on the RDA axes. Details see: https://bio.odb.ntu.edu.tw/query/?help=rda

Body

formdata

config	Query crieteria from bio.odb.ntu.edu.tw/query, or a config text, json, or yaml file.
return_type	“community_rda_plot” return data type, here, “community_rda_plot” return ordination plot by Redundancy Analysis. Specifying “/json” in API endpoint and “community_rda_axis”, “community_rda_species”, or “community_rda_env” in return_type will return tables of site scores, species scores, and env factors fitted on RDA axes, respectively; Similarily, “community_rda” return all statistics table of RDA in a nested json format. Note that env factors should not have too many missing values spatially, otherwise the RDA may fail. Use “en_kriging” in argument ’’getenv_options" may interpolate over some missing points in env.
env_layer	‘["depth","chl","salinity"]’ Environmental layer name that used in the specified “envsrc”. See BioQuery: bio.odb.ntu.edu.tw/query to find all options for env_layer. Specify multiple env layers by using json string, or equivalently in cURL, using curl -F “env_layer=["depth","chl","nitrate"]”.
envsrc	‘["depth","nasa_neo","ncep_godas"]’ Environmental source ‘depth’, which is ODB sea-depth database. Envsrc is either a file with longitude/latitude/(season)/env_layer, or a env database provided (or compiled) by ODB, NTU. See BioQuery: bio.odb.ntu.edu.tw/query to find all options for envsrc. Specify multiple env sources, respectively, by using json string, or equivalently in cURL, using curl -F “envsrc= ["depth","nasa_neo","noaa_wod"]”.
getenv_options	‘{"en_trans":["0","1","0"], "scale_fun":["c","log","c"], "scale_mul":["1","1000","1"], "en_kriging":["0","0","0"]}’ Optional. Json string that specify env_layer need transformation (en_trans: 1/0) by multipling a factor (scal_mul), by functions (scale_fun: “log”, “sqrt”, “exp”,…), or kriging (en_kriging: 1/0). Note: kriging is time-consuming

cURL

Example Request: bioquery RDA ordination

curl --location --request POST "https://bio.odb.ntu.edu.tw/api/bioquery/png" \
  --form "config=@Your_File_Path" \
  --form "return_type=\"community_rda_plot\"" \
  --form "env_layer='[\"depth\",\"chl\",\"salinity\"]'" \
  --form "envsrc='[\"depth\",\"nasa_neo\",\"ncep_godas\"]'" \
  --form "getenv_options='{\"en_trans\":[\"0\",\"1\",\"0\"], \"scale_fun\":[\"c\",\"log\",\"c\"], \"scale_mul\":[\"1\",\"1000\",\"1\"], \"en_kriging\":[\"0\",\"0\",\"0\"]}'" -o output.png

Response

Ordination plot for sites, species, and env factors fitted on RDA axes

Open API.07

POST

keyword: bioquery community bubble-plot

API cURL url: https://bio.odb.ntu.edu.tw/api/bioquery/png {pdf, svg}

API to plot distribution map of community abundance or species diversity, as well as your own data layer, of each grid by bubble plot. Transformation of data value and overlay with env layer are allowed. Details see: https://bio.odb.ntu.edu.tw/query/?help=bubble_plot

Body

formdata

config	Query crieteria from bio.odb.ntu.edu.tw/query, or a config text, json, or yaml file.
return_type	“community_stats_bubble” return data type, here, “community_stats_bubble” return distribution plot of community abundance or species diversity, depends on the argument ‘bubble_stats_layer’. Note that estimate diversity is time-consuming, if just need community abundance, specify ‘abundance_bubble’ will speed-up this evaluation. Details see: https://bio.odb.ntu.edu.tw/query/?help=bubble_plot
bubble_stats_layer	“div” Specify which variable in data should be plotted as bubbles on map, e.g. ‘div’ means species diversity, ‘Hill’ means Hill N1 diversity (case insensitive), ‘abundance’ means community abundance. User can specify any quantized variable in upload file to plot as bubbles.
val_trans	“exp” Optional. Specify which transformation should be appled to the values of ‘bubble_stats_layer’, e.g., ‘exp’ means exponential, ‘identity’ means keep the same value (no transformation), ‘log’ means natural logarithm, and ‘sqrt’ means square-root transformation.
val_label	“Shannon Diversity” Optional. Specify how to label ‘bubble_stats_layer’ on result plot.
env_layer	“depth” Optional. Environmental layer name that used in the specified “envsrc”. See BioQuery: bio.odb.ntu.edu.tw/query to find all options for env_layer. Specify multiple env layers by using json string, or equivalently in cURL, using curl -F “env_layer=["depth","chl","nitrate"]”.
envsrc	“depth” Optional. Environmental source ‘depth’, which is ODB sea-depth database. Envsrc is either a file with longitude/latitude/(season)/env_layer, or a env database provided (or compiled) by ODB, NTU. See BioQuery: bio.odb.ntu.edu.tw/query to find all options for envsrc.
grd_sel	0 Optional. Specify grid for data gridding: null (raw data), 0 (0.25-deg), 1 (0.5-deg, default), 2 (1-deg)
by_season	false Optional. Subdivide results into seasonality (0-3 from spring to winter, respectively).
legend_pos	“topleft” Optional. Legend positon: “none” (no legend) “bottomright”, “topleft”, “right”, “bottom”, and so on
env_fill_palette	“magma” Optional. Specify palette for ‘env_layer’. Colors see here: “The viridis color palettes” http://bit.ly/2XCjPiE
color	“rainbow” Optional. Specify polygonal region colors. Support: viridis-sets (see aboving), R basic paletes (e.g. rainbow, topo.colors, etc), RColorBrewer palettes (e.g. Spectral), also single color name (e.g. black).
scale_res	“large” Optional. Coastline resolution: “small”, “medium”, “large”

cURL

Example Request: bioquery community bubble-plot

curl --location --request POST "https://bio.odb.ntu.edu.tw/api/bioquery/png" \
  --form "config=@Your_File_Path" \
  --form "return_type=\"community_stats_bubble\"" \
  --form "bubble_stats_layer=\"div\"" \
  --form "val_trans=\"exp\"" \
  --form "val_label=\"Shannon Diversity\"" \
  --form "env_layer=\"depth\"" \
  --form "envsrc=\"depth\"" \
  --form "grd_sel=0" \
  --form "by_season=false" \
  --form "legend_pos=\"topleft\"" \
  --form "env_fill_palette=\"magma\"" \
  --form "color=\"rainbow\"" \
  --form "scale_res=\"large\"" -o output.png

Response

Bubble plot of species diversity distribution on map, overlying sea depth

Appendix

Configuration file in YAML for bio.odb.ntu.edu.tw/query

cURL: -F “config=@Your_YAML.yaml”

keyword: config argument YAML

--- 
-
    taxa_sel: larval fish
    season_sel:
    date: 1965-01-01,2019-01-15
    depth: 0,
    mesh: 200,1000
    grid: -1
    ana_level: species
    abundance: 0
    unit: perm3
    subset_xy: FALSE
    lng_lat: NA,NA
    poly: POLYGON 18475 ((121.816406,121.816406,127.485352,127.485352,121.816406,25.76032,31.802893,31.802893,25.76032,25.76032));POLYGON 18529 ((119.179688,120.717773,121.420898,121.772461,120.19043,118.916016,119.179688,26.74561,26.549223,26.627818,25.284438,23.765237,23.80545,26.74561));POLYGON 18607 ((121.464844,123.991699,130.36377,130.627441,120.981445,120.717773,121.464844,23.584126,23.402765,21.902278,20.899871,21.166484,22.492257,23.584126));POLYGON 18858 ((118.850098,118.850098,120.783691,120.783691,118.850098,17.811456,22.857195,22.857195,17.811456,17.811456))

taxa_sel: target taxon group for querying ODB bio-database.

season_sel: #0,1,2,3: Spring, Summer, Autumn, Winter (none means all seasons will be queryed).

date: date range required.

depth: depth range in meter.

grid: grid for data gridding: -1 (raw data), 0 (0.25-deg), 1 (0.5-deg, default), 2 (1-deg), 3 (2-deg).

ana_level: required data in which classification level: species, genus, family, and so on.

abundance: 0 (abundance data), 1 (occurrence data).

unit: perm3 abundance unit of “individuals per m3”; perm2 (individuals per 2) for benthic.

subset_xy: FALSE (depreciated function, just leave it FALSE).

lng_lat: Geographic bounding box in (xmin, xmax, ymin, ymax) format.

poly: Polygonal regions in format “POLYGON” polyID-1 ((lng1, lng2,…, lat1, lat2, …)); “POLYGON” polyID-2 (( polygon coordinates))

Open API return_type definition

keyword: return type argument

return_type: A character string indicated data return type, including:

metadata return metadata of ODB bio-database. (default)
citation return references of data source citations in ODB bio-database.
taxonomy return taxonomy (family, genus, species) in ODB bio-database.
user_data return user data after manipulation
env_list return brief of env data ODB have, that can used to applied to env_layer and envsrc.
env return env data by specifying env_layer and envsrc
site return geo-location of sites.
site2map return the plot of site map @seealso geo2map.
site2wwwmap return the interactive html of site map. API cURL endpoint should be ‘’ to return a self-contained html file. @seealso geo2wwwmap.
rarefaction_plot return the plot of rarefaction curves evaluated by iNEXT.
estimate_diversity_by_samplesize return estimation of diversity from iNEXT rarefacition by sample size.
estimate_diversity_by_coverage return estimation of diversity from iNEXT rarefacition by sample coverage.
community_stats return community abundance and diversity data with env
community_stats_bubble return bubble plot for community abundance or diversity on map @seealso geo2map.
community_rda_plot return ordination plot by Redundancy Analysis (RDA) for species composition and env
community_rda return a two-level list including all RDA statistics (should be a multi-level json to client). ‘community_rda_axis’, as well as with ’_species’ and ’_env’, are allowed to return only one table for site scores, species scores, and env fitted on the RDA axes, respectively.
abundance_stats return only community abundance with env (i.e, without calculating diversity and therefore would be faster).
abundance_bubble return bubble plot for community abundance on map. @seealso geo2map.

Open API technical citation

keyword: rstats R-package citation

See here: Technical citations 本站技術引用

BioQuery API

cyrain＠gmail.com

2019-07-11

Open API.01

POST

Body

cURL

Response

Open API.02

POST

Body

cURL

Response

Open API.03

POST

Body

cURL

Response

Open API.04

POST

Body

cURL

Response

Open API.05

POST

Body

cURL

Response

Open API.06

POST

Body

cURL

Response

Open API.07

POST

Body

cURL

Response

Appendix

Configuration file in YAML for bio.odb.ntu.edu.tw/query

cURL: -F “config=@Your_YAML.yaml”

taxa_sel: target taxon group for querying ODB bio-database.

season_sel: #0,1,2,3: Spring, Summer, Autumn, Winter (none means all seasons will be queryed).

date: date range required.

depth: depth range in meter.

grid: grid for data gridding: -1 (raw data), 0 (0.25-deg), 1 (0.5-deg, default), 2 (1-deg), 3 (2-deg).

ana_level: required data in which classification level: species, genus, family, and so on.

abundance: 0 (abundance data), 1 (occurrence data).

unit: perm3 abundance unit of “individuals per m3”; perm2 (individuals per 2) for benthic.

subset_xy: FALSE (depreciated function, just leave it FALSE).

lng_lat: Geographic bounding box in (xmin, xmax, ymin, ymax) format.

poly: Polygonal regions in format “POLYGON” polyID-1 ((lng1, lng2,…, lat1, lat2, …)); “POLYGON” polyID-2 (( polygon coordinates))

Open API return_type definition

Open API technical citation