API documentation

This is a public, read-only API to the animal audiograms database. Please see the usage examples.

audiogram

Returns all data points for a given audiogram.

Parameters
----------
id : int, required database identifier of an audiogram

Returns
----------
A string in json format containing for each data point:
# audiogram_experiment_id : int database identifier of the experiment this data point belongs to
# id : int database identifier of this data point
# sound_pressure_level_in_decibel : float SPL relative to sound_pressure_level_reference_id
# sound_pressure_level_reference_id : int database identifier of the sound pressure level reference
# sound_pressure_level_reference_method : string root mean squared (RMS) | peak to peak (PP)
# testtone_duration_in_millisecond : float test tone duration
# testtone_frequency_in_khz : float test tone frequency

Raises
----------
Exception if no id was given

Example
---------
https://animalaudiograms.museumfuernaturkunde.berlin/api/v1/audiogram?id=118
Returns a json string with all data points of audiogram 118

browse

Returns a list of short audiogram descriptions.
This method can be used to query the database.

Parameters
----------
# order_by : string vernacular_name_english (default) | species_name (i.e. latin name)|
   citation_short | measurement_method
# species : int id of the species in the database
# taxon : int id of the species in the database (same as species)
# method : int id of the measurement method in the database
# publication : int id of the publication in the database
# facility : int id of the facility in the database
# from : year of the experiment (range start)
# to : year of the experiment (range end)
# medium : string air | water
# sex : string male | female
# liberty : string status of liberty of the animal captive | stranded | wild
# lifestage : string life stage of the animal juvenile | adult | sub-adult
# duration_in_captivity_from : int duration in captivity of the animal in months (range start)
# duration_in_captivity_to : int duration in captivity of the animal in months (range end)
# sedated : whether the animal was sedated yes | no
# age_from : int age of the animal in months (range start)
# age_to : int age of the animal in months (range end)
# distance_from : int distance to the sound source in meters (range start)
# distance_to : int distance to the sound source in meters (range end)
# position: comma-separated list of string position of the animal during the experiment in-air and underwater|totally underwater|head just below water surface|head half out of water|outside of the water|totally above water
# threshold_from : float Threshold determination info in % (range start)
# threshold_to : float Threshold determination info in % (range end)
# tone : int form of the tone
# staircase : string staircase procedure yes | none
# form : comma-separated list of string form of the sound click | pipe trains | prolonged |SAM (sinusoidal amplitude modulation)
# constants : string method of constants yes | no

Returns
----------
A string in json format containing for each audiogram requested in the ids parameter:
# citation_short : citation in short form of the original article
# id : database id of the audiogram
# measurement_method : name of the experimental method used to obtain the audiogram
# species_name : scientific name of the animal species examined
# vernacular_name-english : english name of the animal species examined

Raises
----------
Exception
   If no audiogram ids were given

Example
---------
With no parameters:
https://animalaudiograms.museumfuernaturkunde.berlin/api/v1/browse
Returns a json string with a short description of all audiograms in the database,
ordered by English vernacular name of animal species.

With parameters: filtering by measurement method
https://animalaudiograms.museumfuernaturkunde.berlin/api/v1/browse?order_by=species_name&method=1
Returns a json string with a short description of all audiograms in the database
obtained through behavioral methods and ordered by scientific name of animal species.

With parameters: filtering by year
https://animalaudiograms.museumfuernaturkunde.berlin/api/v1/browse?order_by=measurement_method&from=2018
Returns a json string with a short description of all audiograms in the database
obtained since 2018 (included) and ordered by measurement_method.

experiment

Returns experiment metadata.

Parameters
----------
id : int, required id of an audiogram

Returns
----------
Metadata of the experiment perfomed to obtain this audiogram, in json format
# background_noise_in_decibel : int (mostly empty)
# calibration : text description of how the experiment was calibrated
# distance_to_sound_source_in_meter : int
# facility_name : string name of the institution etc. where the experiment was carried out
# latitude_in_decimal_degree : float (mostly empty)
# longitude_in_decimal_degree : float (mostly empty)
# measurement_method : string name of the measurement method used to obtain this audiogram (e.g. "behavioral: go - no go")
# medium : string water | air
# number_of_measurements: int count of measurements, when known
# position_first_electrode : string placement of the electrode when applying electrophysiological methods
# position_second_electrode : string placement of the electrode when applying electrophysiological methods
# position_third_electrode : string placement of the electrode when applying electrophysiological methods
# position_of_animal : string position of the animal during the experiment (e.g. "totally underwater")
# sedated : string yes | no
# sedation_details : string description of the sedation method
# test_environment_description : text test environment details and comments
# testtone_form_method : string e.g. "sinusoidal frequency modulated tone (FM)"
# testtone_presentation_method_constants : string yes | no
# testtone_presentation_sound_form : string e.g. "click"
# testtone_presentation_staircase : string yes | no
# threshold_determination_method : float in %
# year_of_experiment : year in YYYY format

Raises
----------
Exception if no id was given

Example
---------
https://animalaudiograms.museumfuernaturkunde.berlin/api/v1/experiment?id=253
Returns a json string with all available experiment metadata on audiogram 253

is_compatible

Checks that requested audiograms have compatible units.
Units are compatible if the audiograms have been obtained in the same medium (water or air).

Parameters
----------
ids : comma-separated list of int, required
   ids of audiograms

Returns
----------
"true" or "false"

Raises
----------
Exception
   If no audiogram ids were given

Example
---------
https://animalaudiograms.museumfuernaturkunde.berlin/api/v1/is_compatible?ids=187,186
Returns "true"

summary

Summarizes the data in the database.

Parameters
----------
none

Returns
----------
A string in json format containing:
# "in_air" : number of audiograms obtained in air
# "in_air_species" : number of animal species for which in air audiograms are recorded in the database
# in_water : number of audiograms obtaine in water
# "in_water_species" : number of animal species for which in water audiograms are recorded in the database

Raises
----------
none

Example
---------
https://animalaudiograms.museumfuernaturkunde.berlin/api/v1/summary
Returns a json string describing the current contents of the database

list

Returns a list of short audiogram descriptions.

Parameters
----------
ids : comma-separated list of int, required
   ids of audiograms

Returns
----------
A string in json format containing for each audiogram requested in the ids parameter:
# citation_short : citation in short form of the original article
# id : database id of the audiogram
# measurement_method : name of the experimental method used to obtain the audiogram
# species_name : scientific name of the animal species examined
# vernacular_name-english : english name of the animal species examined

Raises
----------
Exception
   If no audiogram ids were given

Example
---------
https://animalaudiograms.museumfuernaturkunde.berlin/api/v1/list?ids=186,187
Returns a json string with a short description of audiograms 186 and 187

plot

Returns information of the plotting process when plotting a single audiogram.

Parameters
----------
id : int, required database identifier of an audiogram

Returns
----------
A json object describing the status of the plotting process
# Location : URL status of the plotting process.
Opening this URL gives information whether the plotting process is completed,
and if so, the URL of the plot image.

Raises
----------
Exception if no id was given

Example
---------
https://animalaudiograms.museumfuernaturkunde.berlin/api/v1/audiogram?plot=118
Returns a json string with the status of the plotting process

plotlayers

Returns information of the plotting process when plotting audiogram overlays.

Parameters
----------
ids : comma-separated list of int, required database identifier of audiograms

Returns
----------
A json object describing the status of the plotting process
# Location : URL status of the plotting process.
Opening this URL gives information whether the plotting process is completed,
and if so, the URL of the plot image.

Raises
----------
Exception if no id was given

Example
---------
https://animalaudiograms.museumfuernaturkunde.berlin/api/v1/audiogram?plot=118
Returns a json string with the status of the plotting process

/status/<task_id>

Return a progress report on the plotting process.

Parameters
----------
none

Returns
----------
A progress report in json format
# state : string 'PENDING' | 'FAILURE' | 'SUCCESS'
# current : int progress in %
# total : int progress in % of result
# status : string verbose descruption of process state
# result : URL of plot image

Raises
----------
Exception if no id was given

Example
---------
see get_plot

caption

Returns a caption for an audiogram plot.

Parameters
----------
id : int, required id of an audiogram

Returns
----------
Caption of the audiogram, in json format
# citation_short : citation in short form of the original article
# species_name : scientific name of the animal species examined
# vernacular_name-english : english name of the animal species examined

Raises
----------
Exception if no id was given

Example
----------
http://localhost:9082/api/v1/caption?id=111
Returns a json string with citation in short form, latin and vernacular name of the species.

data

Returns all data points for a given audiogram and SPL unit used in the experiment.

Parameters
----------
id : int, required id of an audiogram

Parameters
----------
id : int, required database identifier of an audiogram

Returns
----------
A string in json format containing for each data point:
# audiogram_experiment_id : int database identifier of the experiment this data point belongs to
# conversion_factor_airborne_sound_in_decibel
# conversion_factor_waterborne_sound_in_decibel
# sound_pressure_level_in_decibel : float SPL relative to sound_pressure_level_reference_id
# sound_pressure_level_reference_id : int database identifier of the sound pressure level reference
# sound_pressure_level_reference_method : string root mean squared (RMS) | peak to peak (PP)
# spl_reference_display_label : string human-readable representation of the SPL reference (e.g. re 1 μPa)
# spl_reference_significance : whether the SPL reference is current or deprecated, in-air or in-water
# spl_reference_unit : string unit of the SPL reference (e.g. "μPa")
# spl_reference_value : value of the SPL reference in the given unit (e.g. "1")
# testtone_duration_in_millisecond : float test tone duration
# testtone_frequency_in_khz : float test tone frequency

Raises
----------
Exception if no id was given

Example
---------
https://animalaudiograms.museumfuernaturkunde.berlin/api/v1/data?id=118
Returns a json string with all data points of audiogram 118 and corresponding SPL reference unit

animal

Returns data on the  animal involved in this experiment.

Parameters
----------
id : int, required id of an audiogram

Parameters
----------
id : int, required database identifier of an audiogram

Returns
----------
A string in json format containing information on the animal:
# age_in_month : int age of the animal in months,
# biological_season : not used,
# captivity_duration_in_month : int duration in captivity of the animal in months,
# individual_name : string name (or identifier) of the animal,
# liberty_status : string status of liberty of the animal captive | stranded | wild
# lifestage : string life stage of the animal juvenile | adult | sub-adult
# sex : string male | female
# species_name : scientific name of the animal species examined
# vernacular_name-english : english name of the animal species examined

Raises
----------
Exception if no id was given

Example
---------
http://localhost:9082/api/v1/animal?id=111
Returns a json string with the information on the animal (harbour porpoise in this case),
its age and captivity status.

species

Returns latin name and vernacular name of the species of the animal involved in experiment.

Parameters
----------
id : int, required database identifier of an audiogram

Returns
----------
A string in json format containing information on the animal:
# species_name : scientific name of the animal species examined
# vernacular_name-english : english name of the animal species examined

Example
---------
http://localhost:9082/api/v1/species?id=111
Returns a json string with the information on the animal species (harbour porpoise in this case)

all_species

Returns all animal species in database (latin names), and audiogram counts per species.

Parameters
----------
id : int, required database identifier of an audiogram

Returns
----------
A list in json format containing information on the species recorded in the database:
# ott_id : int species identifier, references the Open Tree of Life database
# taxon_name : latin name of a species
# total : int audiogram count for this species

Example
---------
http://localhost:9082/api/v1/all_species
Returns a list of species currently recorded in the database.

all_species_vernacular

Returns all animal species in database (English names), and audiogram counts per species.

Parameters
----------
none

Returns
----------
A list in json format containing information on the species recorded in the database:
# ott_id : int species identifier, references the Open Tree of Life database
# vernacular_name_english : latin name of a species
# total : int audiogram count for this species

Example
---------
http://localhost:9082/api/v1/all_species_vernacular
Returns a list of species currently recorded in the database.

all_measurement_methods

Returns all measurement methods in database.

Parameters
----------
none

Returns
----------
A list in json format containing all measurement methods recorded in the database:
# method_id : int internal database identifier of this method
# method_name : string name of the method. Method names are composed of:
a generic method name ("behavioral" or "electrophysiological") and
a specific method name (e.g. "behavioral: go - no go")

Example
---------
http://localhost:9082/api/v1/all_methods
Returns a list of measurement methods currently recorded in the database.

parent_measurement_methods

Returns high-level, generic measurement methods in database.

Parameters
----------
none

Returns
----------
A list in json format containing all generic measurement methods recorded in the database:
# method_id : int internal database identifier of this method
# method_name : string generic method name ("behavioral" or "electrophysiological")

Example
---------
http://localhost:9082/api/v1/parent_measurement_methods
Returns a list of generic measurement methods currently recorded in the database.

all_tone_methods

Returns all tone methods in database.

Parameters
----------
none

Returns
----------
A list in json format containing all measurement methods recorded in the database:
# method_id : int internal database identifier of this method
# method_name : string name of the method.

Example
---------
http://localhost:9082/api/v1/all_tone_methods
Returns a list of tone methods currently recorded in the database.

all_publications

Return all publications in database, in short form.

Parameters
----------
none

Returns
----------
A list in json format containing all publications recorded in the database:
# id : int internal database identifier of this publication
# citation_short : citation in short form of the original article

Example
---------
http://localhost:9082/api/v1/all_publications
Returns a list of publications currently recorded in the database.

all_facilities

Returns all research facilities in database.

Parameters
----------
none

Returns
----------
A list in json format containing all facilities recorded in the database:
# id : int internal database identifier of this facility
# name : name of the facility

Example
---------
http://localhost:9082/api/v1/all_facilities
Returns a list of facilities currently recorded in the database.

all_birds

Returns all audiograms of birds.

Parameters
----------
none

Returns
----------
A list in json format containing information on the audiograms of birds recorded in the database:
# ott_id : int species identifier, references the Open Tree of Life database
# unique_name : latin name of a species
# audiogram_experiment_id : int id of an audiogram
# medium : string "air" | "water"

Example
---------
http://localhost:9082/api/v1/all_birds
Returns a list of audiograms of birds.

all_reptiles

Returns all audiograms of reptiles.

Parameters
----------
none

Returns
----------
A list in json format containing information on the audiograms of reptiles recorded in the database:
# ott_id : int species identifier, references the Open Tree of Life database
# unique_name : latin name of a species
# audiogram_experiment_id : int id of an audiogram
# medium : string "air" | "water"

Example
---------
http://localhost:9082/api/v1/all_reptiles
Returns a list of audiograms of reptiles.

all_fishes

Returns all audiograms of fishes.

Parameters
----------
none

Returns
----------
A list in json format containing information on the audiograms of fishes recorded in the database:
# ott_id : int species identifier, references the Open Tree of Life database
# unique_name : latin name of a species
# audiogram_experiment_id : int id of an audiogram
# medium : string "air" | "water"

Example
---------
http://localhost:9082/api/v1/all_fishes
Returns a list of audiograms of fishes.

all_mammals

Returns all audiograms of mammals.

Parameters
----------
none

Returns
----------
A list in json format containing information on the audiograms of mammals recorded in the database:
# ott_id : int species identifier, references the Open Tree of Life database
# unique_name : latin name of a species
# audiogram_experiment_id : int id of an audiogram
# medium : string "air" | "water"

Example
---------
http://localhost:9082/api/v1/all_mammals
Returns a list of audiograms of mammals.

all_cetaceans

Returns all audiograms of cetaceans.

Parameters
----------
none

Returns
----------
A list in json format containing information on the audiograms of cetaceans recorded in the database:
# ott_id : int species identifier, references the Open Tree of Life database
# unique_name : latin name of a species
# audiogram_experiment_id : int id of an audiogram
# medium : string "air" | "water"

Example
---------
http://localhost:9082/api/v1/all_cetaceans
Returns a list of audiograms of cetaceans.

all_seals

Returns all audiograms of seals.

Parameters
----------
none

Returns
----------
A list in json format containing information on the audiograms of seals recorded in the database:
# ott_id : int species identifier, references the Open Tree of Life database
# unique_name : latin name of a species
# audiogram_experiment_id : int id of an audiogram
# medium : string "air" | "water"

Example
---------
http://localhost:9082/api/v1/all_seals
Returns a list of audiograms of seals.

publication

Returns the publication associated with an audiogram.

Parameters
----------
id : int identifier of an audiogram

Returns
----------
A string in json format representing teh publication where this audiogram comes from
# DOI : string DOI of the publication
# citation_long : string (Harvard) formatted citation of the publication

Raises
----------
Exception when no id was given

Example
---------
http://localhost:9082/api/v1/publication?id=5
Returns citation and DOI for audiogram nr 5.

taxonomy

Returns full taxonomy in database.

Parameters
----------
none

Returns
----------
A list of tree nodes in json format. Each node has these attributes:
# ott_id : int identifier of the taxon in the Open Tree of Life resource
# parent : int ott_id of the parent node in the tree
# rank : string taxonomic rank of the node (e.g. "subspecies", "species", "order", "family", "class")
# unique_name : string latin name of the taxon
# vernacular_name_english : string common English name of the taxon
# vernacular_name_german : string common German name of the taxon
# lft : int nested set left-side index of the node
# rft : int nested set right-side index of the node

Example
---------
http://localhost:9082/api/v1/taxonomy
Returns the complete taxonomy stored in the database

download

Returns downloadable data for given audiogram.
Downloadable data is in the original units, which may be different
from the units used to display the audiogram in the Web interface.

Parameters
----------
id : int, required
   id of an audiogram

Returns
----------
A file in CSV format with a row for each data point.

Raises
----------
Exception
   If no audiogram id was given

Example
---------
https://animalaudiograms.museumfuernaturkunde.berlin/api/v1/download?id=111
Returns the data for audiogram 111 as a downloadable csv file.