NAV Navbar
shell ruby r

Introduction

Welcome to the BIEN API!

We have examples for Shell, Ruby, and R. You can view code examples in the dark area to the right, and you can switch the programming language of the examples with the tabs in the top right.

Authentication

An API token is required for most routes. Tokens are passed in a header like Authorization: token, for example: curl -H "Authorization: token" https://bienapi.xyz.

Get a token using the /token route.

Data format

You can get two types of data back from this API: JSON and CSV. The way you toggle this behavior is through the HTTP Accept header. The default type is JSON; if you want JSON you don't need to set the Accept header, but you can if you want.

To get CSV back, you'll need to set the Accept header as Accept: text/csv.

To set the header for JSON do Accept: application/json.

A few routes ignore the Accept header and always return JSON: /token, /authorized, and /heartbeat

Heartbeat

List all API routes

require 'faraday'

con = Faraday.new(url: "https://bienapi.xyz")
res = con.get '/heartbeat'
res.body
curl https://bienapi.xyz/heartbeat
library(crul)
con <- HttpClient$new("https://bienapi.xyz")
con$get("heartbeat")

The above command returns JSON structured like this:

{
  "routes": [
    "/token/?",
    "/authorized/?",
    "/?",
    "/heartbeat/?",
    "/list/?",
    "/list/country/?",
    "/plot/metadata/?",
    "/plot/protocols/?",
    "/traits/?",
    "/traits/family/?",
    "/traits/family/:id/?",
    "/occurrence/species/?",
    "/occurrence/genus/?",
    "/occurrence/family/?",
    "/occurrence/count/?",
    "/taxonomy/species/?",
    "/taxonomy/genus/?",
    "/taxonomy/family/?",
    "/phylogeny/?",
    "/meta/version/?",
    "/meta/citations/traits/:id/?",
    "/meta/citations/occurrence/:id/?",
    "/meta/politicalnames/?",
    "/ranges/list/?",
    "/ranges/species/?",
    "/ranges/genus/?",
    "/ranges/spatial/?",
    "/stem/species/?",
    "/stem/genus/?",
    "/stem/family/?",
    "/stem/datasource/?"
  ]
}

GET https://bienapi.xyz/heartbeat

Token

Get an API key/token

Store the token, ideally in an environment variable, for example: BIEN_API_KEY. We use BIEN_API_KEY in the examples throughout the documentation here.

require 'faraday'

con = Faraday.new(url: "https://bienapi.xyz")
res = con.get '/token', {:email => "jane.doe@gmail.com"}
res.body
curl https://bienapi.xyz/token?email=jane.doe@gmail.com
library(crul)
con <- HttpClient$new("https://bienapi.xyz")
con$get("token", query = list(email = "jane.doe@gmail.com"))

The above command returns JSON structured like this:

{
  "email": "jane.doe@gmail.com",
  "token": "<token>"
}

GET https://bienapi.xyz/token

Authorized?

Check that your BIEN API key/token is valid

require 'faraday'

con = Faraday.new(url: "https://bienapi.xyz")
con.headers[:authorization] = ENV["BIEN_API_KEY"]
res = con.get '/authorized'
res.body
curl -H 'Authorization: '"$BIEN_API_KEY"'' \
  "https://bienapi.xyz/authorized"
library(crul)
auth <- list(Authorization = Sys.getenv('BIEN_API_KEY'))
con <- HttpClient$new("https://bienapi.xyz", headers = auth)
con$get("authorized")

The above command returns JSON structured like this:

{
  "authorized": true
}

If not authorized, you'll get a 403 error:

{
  "error": "token not found; get a token first with the /token route"
}

GET https://bienapi.xyz/authorized

Species lists

Extract species lists

require 'faraday'

con = Faraday.new(url: "https://bienapi.xyz")
con.headers[:authorization] = ENV["BIEN_API_KEY"]
res = con.get '/list'
res.body
curl -H 'Authorization: '"$BIEN_API_KEY"'' \
  "https://bienapi.xyz/list"
library(crul)
auth <- list(Authorization = Sys.getenv('BIEN_API_KEY'))
con <- HttpClient$new("https://bienapi.xyz", headers = auth)
con$get("list")

The above command returns JSON structured like this:

{
  "count": 331065,
  "returned": 10,
  "data": [
    {
      "species": "Aa achalensis"
    },
    {
      "species": "Aa argyrolepis"
    },
    {
      "species": "Aa calceata"
    }
  ],
  "error": null
}

GET https://bienapi.xyz/list

Query Parameters

Parameter Default Description
limit 10 number of results to return (max: 1000)
offset 0 record number to start at

Extract species lists by country

require 'faraday'

con = Faraday.new(url: "https://bienapi.xyz")
con.headers[:authorization] = ENV["BIEN_API_KEY"]
res = con.get '/list/country'
res.body
curl -H 'Authorization: '"$BIEN_API_KEY"'' \
  "https://bienapi.xyz/list/country?country=Canada"
library(crul)
auth <- list(Authorization = Sys.getenv('BIEN_API_KEY'))
con <- HttpClient$new("https://bienapi.xyz", headers = auth)
con$get("list/country", query = list(country = "Canada"))

The above command returns JSON structured like this:

{
  "count": 1,
  "returned": 10,
  "data": [
    {
      "species_by_political_division_id": null,
      "scrubbed_species_binomial": "Abelia grandiflora",
      "country": "Canada",
      "is_new_world": 1,
      "is_cultivated_observation": null,
      "is_cultivated_in_region": 0
    },
    {
      "species_by_political_division_id": null,
      "scrubbed_species_binomial": "Abelia xgrandiflora",
      "country": "Canada",
      "is_new_world": 1,
      "is_cultivated_observation": null,
      "is_cultivated_in_region": 0
    }
  ],
  "error": null
}

GET https://bienapi.xyz/list/country

Query Parameters

Parameter Default Description
country_code NULL country code
cultivated false return cultivated records as well?
only_new_world false return only records from the New World?
limit 10 number of results to return (max: 1000)
offset 0 record number to start at

Plot

Plot Metadata

require 'faraday'

con = Faraday.new(url: "https://bienapi.xyz")
con.headers[:authorization] = ENV["BIEN_API_KEY"]
res = con.get '/plot/metadata'
res.body
curl -H 'Authorization: '"$BIEN_API_KEY"'' \
  "https://bienapi.xyz/plot/metadata"
library(crul)
auth <- list(Authorization = Sys.getenv('BIEN_API_KEY'))
con <- HttpClient$new("https://bienapi.xyz", headers = auth)
con$get("plot/metadata")

The above command returns JSON structured like this:

{
  "count": 631121,
  "returned": 10,
  "data": [
    {
      "plot_metadata_id": 2183
    },
    {
      "plot_metadata_id": 2204
    }
  ],
  "error": null
}

GET https://bienapi.xyz/plot/metadata

Query Parameters

Parameter Default Description
fields NULL fields to return, by dafault all are returned
limit 10 number of results to return (max: 1000)
offset 0 record number to start at

Plot Metadata protocols

require 'faraday'

con = Faraday.new(url: "https://bienapi.xyz")
con.headers[:authorization] = ENV["BIEN_API_KEY"]
res = con.get '/plot/protocols'
res.body
curl -H 'Authorization: '"$BIEN_API_KEY"'' \
  "https://bienapi.xyz/plot/protocols"
library(crul)
auth <- list(Authorization = Sys.getenv('BIEN_API_KEY'))
con <- HttpClient$new("https://bienapi.xyz", headers = auth)
con$get("plot/metadata/protocols")

The above command returns JSON structured like this:

{
  "count": 1,
  "returned": 9,
  "data": [
    {
      "sampling_protocol": "",
      "plot_metadata_id": null
    },
    {
      "sampling_protocol": "0.1 ha  transect, stems >= 2.5 cm dbh",
      "plot_metadata_id": null
    }
  ],
  "error": null
}

GET https://bienapi.xyz/plot/protocols

Ranges

Range: list

List available range maps

require 'faraday'

con = Faraday.new(url: "https://bienapi.xyz")
con.headers[:authorization] = ENV["BIEN_API_KEY"]
res = con.get '/ranges/list'
res.body
curl -H 'Authorization: '"$BIEN_API_KEY"'' \
  "https://bienapi.xyz/ranges/list"
library(crul)
auth <- list(Authorization = Sys.getenv('BIEN_API_KEY'))
con <- HttpClient$new("https://bienapi.xyz", headers = auth)
con$get("ranges/list")

The above command returns JSON structured like this:

{
  "count": 98829,
  "returned": 10,
  "data": [
    {
      "species": "Aa_argyrolepis",
      "gid": 1
    },
    {
      "species": "Aa_colombiana",
      "gid": 2
    }
  ],
  "error": null
}

GET https://bienapi.xyz/ranges/list

Query Parameters

Parameter Default Description
limit 10 number of results to return (max: 1000)
offset 0 record number to start at

Range: species

Range maps for a given species

require 'faraday'

con = Faraday.new(url: "https://bienapi.xyz")
con.headers[:authorization] = ENV["BIEN_API_KEY"]
res = con.get '/ranges/species', {:species => "Abies lasiocarpa"}
res.body
curl -H 'Authorization: '"$BIEN_API_KEY"'' \
  "https://bienapi.xyz/ranges/species?species=Abies%20lasiocarpa"
library(crul)
auth <- list(Authorization = Sys.getenv('BIEN_API_KEY'))
con <- HttpClient$new("https://bienapi.xyz", headers = auth)
con$get("ranges/species", query = list(species = "Abies lasiocarpa"))

The above command returns JSON structured like this:

{
  "count": 1,
  "returned": 1,
  "data": [
    {
      "species": "Abies_lasiocarpa",
      "gid": 90,
      "st_astext": "MULTIPOLYGON(((-107.75178470368 28.3154733778057, ..."
    }
  ],
  "error": null
}

GET https://bienapi.xyz/ranges/species

Query Parameters

Parameter Default Description
limit 10 number of results to return (max: 1000)
offset 0 record number to start at
species NULL a species name (binomial: "genus epithet")
match_names_only false check for range maps for the taxa specified w/o downloading range data

Ranges: genus

require 'faraday'

con = Faraday.new(url: "https://bienapi.xyz")
con.headers[:authorization] = ENV["BIEN_API_KEY"]
res = con.get '/ranges/genus', {:genus => "Abies"}
res.body
curl -H 'Authorization: '"$BIEN_API_KEY"'' \
  "https://bienapi.xyz/ranges/genus?genus=Abies"
library(crul)
auth <- list(Authorization = Sys.getenv('BIEN_API_KEY'))
con <- HttpClient$new("https://bienapi.xyz", headers = auth)
con$get("ranges/genus", query = list(genus = "Abies"))

The above command returns JSON structured like this:

{
  "count": 29,
  "returned": 29,
  "data": [
    {
      "species": "Abies_alba",
      "gid": 73,
      "st_astext": "MULTIPOLYGON(((-77.0940591727373 38.9862810126957, ...)))"
    },
    {
      "species": "Abies_amabilis",
      "gid": 74,
      "st_astext": "MULTIPOLYGON(((-119.61169766459 33.3287672107037, ...)))"
    },
    {
      "species": "Abies_balsamea",
      "gid": 75,
      "st_astext": "MULTIPOLYGON(((-84.0403833648593 35.4759177778039, ...)))"
    }
  ],
  "error": null
}

GET https://bienapi.xyz/ranges/genus

Query Parameters

Parameter Default Description
limit 10 number of results to return (max: 1000)
offset 0 record number to start at
genus NULL a genus name
match_names_only false check for range maps for the taxa specified w/o downloading range data

Ranges: spatial

require 'faraday'

con = Faraday.new(url: "https://bienapi.xyz")
con.headers[:authorization] = ENV["BIEN_API_KEY"]
res = con.get '/ranges/spatial', {:wkt => "POLYGON((-114.03 34.54,-112.67 34.54,-112.67 33.19,-114.03 33.19,-114.03 34.54))"}
res.body
curl -H 'Authorization: '"$BIEN_API_KEY"'' \
  "https://bienapi.xyz/ranges/spatial?wkt=POLYGON((-114.03 34.54,-112.67 34.54,-112.67 33.19,-114.03 33.19,-114.03 34.54))"
library(crul)
auth <- list(Authorization = Sys.getenv('BIEN_API_KEY'))
con <- HttpClient$new("https://bienapi.xyz", headers = auth)
con$get("ranges/spatial", query = list(wkt = "POLYGON((-114.03 34.54,-112.67 34.54,-112.67 33.19,-114.03 33.19,-114.03 34.54))"))

The above command returns JSON structured like this:

{
  "fix": "me"
}

GET https://bienapi.xyz/ranges/spatial

Query Parameters

Parameter Default Description
limit 10 number of results to return (max: 1000)
offset 0 record number to start at
wkt NULL xx
species_names_only false xx
crop_ranges false xx

Stem

Stem: species

Extract stem data for a species

require 'faraday'

con = Faraday.new(url: "https://bienapi.xyz")
con.headers[:authorization] = ENV["BIEN_API_KEY"]
res = con.get '/stem/species', {:species => "Abies amabilis"}
res.body
curl -H 'Authorization: '"$BIEN_API_KEY"'' \
  "https://bienapi.xyz/stem/species?species=Abies%20amabilis"
library(crul)
auth <- list(Authorization = Sys.getenv('BIEN_API_KEY'))
con <- HttpClient$new("https://bienapi.xyz", headers = auth)
con$get("stem/species", query = list(species = "Abies amabilis"))

The above command returns JSON structured like this:

{
  "count": 15619,
  "returned": 10,
  "data": [
    {
      "analytical_stem_id": null,
      "taxonobservation_id": 70784983,
      "datasource_id": 65,
      "datasource": "FIA",
      "dataset": "U.S. Forest Inventory and Analysis (FIA) National Program",
      "dataowner": "Greg Reams",
      "latitude": "48.603513",
      "longitude": "-121.069843",
      "is_new_world": 1
    },
    {
      "analytical_stem_id": null,
      "taxonobservation_id": 70785003,
      "datasource_id": 65,
      "datasource": "FIA",
      "dataset": "U.S. Forest Inventory and Analysis (FIA) National Program",
      "dataowner": "Greg Reams",
      "latitude": "45.351508",
      "longitude": "-121.847807",
      "is_new_world": 1
    }
  ],
  "error": null
}

GET https://bienapi.xyz/stem/species

Query Parameters

Parameter Default Description
limit 10 number of results to return (max: 1000)
offset 0 record number to start at
species NULL a species name (binomial: "genus epithet")

Stem: genus

Extract stem data for a genus

require 'faraday'

con = Faraday.new(url: "https://bienapi.xyz")
con.headers[:authorization] = ENV["BIEN_API_KEY"]
res = con.get '/stem/genus', {:genus => "Tovomita"}
res.body
curl -H 'Authorization: '"$BIEN_API_KEY"'' \
  "https://bienapi.xyz/stem/genus?genus=Tovomita"
library(crul)
auth <- list(Authorization = Sys.getenv('BIEN_API_KEY'))
con <- HttpClient$new("https://bienapi.xyz", headers = auth)
con$get("stem/genus", query = list(genus = "Tovomita"))

The above command returns JSON structured like this:

{
  "count": 460,
  "returned": 10,
  "data": [
    {
      "analytical_stem_id": null,
      "taxonobservation_id": 63198198,
      "datasource_id": 42,
      "datasource": "TEAM",
      "dataset": "Manaus",
      "dataowner": "Eduardo Eler",
      "latitude": "-2.9289898",
      "longitude": "-59.9468382",
      "is_new_world": 1
    },
    {
      "analytical_stem_id": null,
      "taxonobservation_id": 63348187,
      "datasource_id": 42,
      "datasource": "TEAM",
      "dataset": "Manaus",
      "dataowner": "Eduardo Eler",
      "latitude": "-2.9289898",
      "longitude": "-59.9468382",
      "is_new_world": 1
    }
  ],
  "error": null
}

GET https://bienapi.xyz/stem/genus

Query Parameters

Parameter Default Description
limit 10 number of results to return (max: 1000)
offset 0 record number to start at
genus NULL a genus name

Stem: family

Extract stem data for a family

require 'faraday'

con = Faraday.new(url: "https://bienapi.xyz")
con.headers[:authorization] = ENV["BIEN_API_KEY"]
res = con.get '/stem/family', {:family => "Marantaceae"}
res.body
curl -H 'Authorization: '"$BIEN_API_KEY"'' \
  "https://bienapi.xyz/stem/family?family=Marantaceae"
library(crul)
auth <- list(Authorization = Sys.getenv('BIEN_API_KEY'))
con <- HttpClient$new("https://bienapi.xyz", headers = auth)
con$get("stem/family", query = list(family = "Marantaceae"))

The above command returns JSON structured like this:

{
  "count": 30,
  "returned": 10,
  "data": [
    {
      "analytical_stem_id": null,
      "taxonobservation_id": 75556961,
      "datasource_id": 14,
      "datasource": "SALVIAS",
      "dataset": "Gentry Transect Dataset",
      "dataowner": "James S. MIller"
    },
    {
      "analytical_stem_id": null,
      "taxonobservation_id": 75556961,
      "datasource_id": 14,
      "datasource": "SALVIAS",
      "dataset": "Gentry Transect Dataset",
      "dataowner": "James S. MIller"
    }
  ],
  "error": null
}

GET https://bienapi.xyz/stem/family

Query Parameters

Parameter Default Description
limit 10 number of results to return (max: 1000)
offset 0 record number to start at
family NULL a family name

Stem: datasource

Extract stem data for a datasource

require 'faraday'

con = Faraday.new(url: "https://bienapi.xyz")
con.headers[:authorization] = ENV["BIEN_API_KEY"]
res = con.get '/stem/datasource', {:datasource => "SALVIAS"}
res.body
curl -H 'Authorization: '"$BIEN_API_KEY"'' \
  "https://bienapi.xyz/stem/datasource?datasource=SALVIAS" | jq .
library(crul)
auth <- list(Authorization = Sys.getenv('BIEN_API_KEY'))
con <- HttpClient$new("https://bienapi.xyz", headers = auth)
con$get("stem/datasource", query = list(datasource = "SALVIAS"))

The above command returns JSON structured like this:

{
  "count": 188628,
  "returned": 10,
  "data": [
    {
      "analytical_stem_id": null,
      "taxonobservation_id": 31795391,
      "datasource_id": 33,
      "datasource": "SALVIAS",
      "dataset": "La Selva Secondary Forest Plots",
      "dataowner": "Susan Letcher",
      "latitude": "10.399",
      "longitude": "-84.0995"
    },
    {
      "analytical_stem_id": null,
      "taxonobservation_id": 31795391,
      "datasource_id": 33,
      "datasource": "SALVIAS",
      "dataset": "La Selva Secondary Forest Plots",
      "dataowner": "Susan Letcher",
      "latitude": "10.399",
      "longitude": "-84.0995",
      "plot_name": "LSSFP_26"
    }
  ],
  "error": null
}

GET https://bienapi.xyz/stem/datasource

Query Parameters

Parameter Default Description
limit 10 number of results to return (max: 1000)
offset 0 record number to start at
datasource NULL a datasource name

Traits

Traits: list

List all available types of trait data

require 'faraday'

con = Faraday.new(url: "https://bienapi.xyz")
con.headers[:authorization] = ENV["BIEN_API_KEY"]
res = con.get '/traits'
res.body
curl -H 'Authorization: '"$BIEN_API_KEY"'' \
  "https://bienapi.xyz/traits" | jq .
library(crul)
auth <- list(Authorization = Sys.getenv('BIEN_API_KEY'))
con <- HttpClient$new("https://bienapi.xyz", headers = auth)
con$get("traits")

The above command returns JSON structured like this:

{
  "count": 1,
  "returned": 10,
  "data": [
    {
      "id": null,
      "trait_name": "diameter at breast height (1.3 m)"
    },
    {
      "id": null,
      "trait_name": "flower color"
    }
  ],
  "error": null
}

GET https://bienapi.xyz/traits

Query Parameters

Parameter Default Description
limit 10 number of results to return (max: 1000)
offset 0 record number to start at

Traits: family

Extract all trait data for given families

require 'faraday'

con = Faraday.new(url: "https://bienapi.xyz")
con.headers[:authorization] = ENV["BIEN_API_KEY"]
res = con.get '/traits/family', {:family => "Poaceae"}
res.body
curl -H 'Authorization: '"$BIEN_API_KEY"'' \
  "https://bienapi.xyz/traits/family?family=Poaceae" | jq .
library(crul)
auth <- list(Authorization = Sys.getenv('BIEN_API_KEY'))
con <- HttpClient$new("https://bienapi.xyz", headers = auth)
con$get("traits/family", query = list(family = "Poaceae"))

The above command returns JSON structured like this:

{
  "fix": "me"
}

GET https://bienapi.xyz/traits/family

Query Parameters

Parameter Default Description
limit 10 number of results to return (max: 1000)
offset 0 record number to start at

Occurrences

Occurrences: species

Extract occurrence data for a given species

require 'faraday'

con = Faraday.new(url: "https://bienapi.xyz")
con.headers[:authorization] = ENV["BIEN_API_KEY"]
res = con.get '/occurrence/species', {:species => "Pinus contorta"}
res.body
curl -H 'Authorization: '"$BIEN_API_KEY"'' \
  "https://bienapi.xyz/occurrence/species?species=Pinus%20contorta" | jq .
library(crul)
auth <- list(Authorization = Sys.getenv('BIEN_API_KEY'))
con <- HttpClient$new("https://bienapi.xyz", headers = auth)
con$get("occurrence/species", query = list(species = "Pinus contorta"))

The above command returns JSON structured like this:

{
  "count": null,
  "returned": 3,
  "data": [
    {
      "taxonobservation_id": 42841561,
      "datasource_id": 85,
      "datasource": "VegBank",
      "dataset": "Glacier National Park",
      "dataowner": "Steve Cooper",
      "latitude": "48.682812748",
      "longitude": "-113.583088685",
      "date_collected": "2000-07-11",
      "scrubbed_species_binomial": "Pinus contorta"
    },
    {
      "taxonobservation_id": 42898022,
      "datasource_id": 85,
      "datasource": "VegBank",
      "dataset": "Glacier National Park",
      "dataowner": "Steve Cooper",
      "latitude": "48.682812748",
      "longitude": "-113.583088685",
      "date_collected": "2000-07-11",
      "scrubbed_species_binomial": "Pinus contorta"
    }
  ],
  "error": null
}

GET https://bienapi.xyz/occurrence/species/

Query Parameters

Parameter Default Description
limit 10 number of results to return (max: 1000)
offset 0 record number to start at
species NULL a species name (binomial: "genus epithet")

Occurrences: genus

Extract occurrence data for a given genus

require 'faraday'

con = Faraday.new(url: "https://bienapi.xyz")
con.headers[:authorization] = ENV["BIEN_API_KEY"]
res = con.get '/occurrence/genus', {:genus => "Pinus"}
res.body
curl -H 'Authorization: '"$BIEN_API_KEY"'' \
  "https://bienapi.xyz/occurrence/genus?genus=Pinus" | jq .
library(crul)
auth <- list(Authorization = Sys.getenv('BIEN_API_KEY'))
con <- HttpClient$new("https://bienapi.xyz", headers = auth)
con$get("occurrence/genus", query = list(genus = "Pinus"))

The above command returns JSON structured like this:

{
  "count": null,
  "returned": 4,
  "data": [
    {
      "taxonobservation_id": 38103840,
      "datasource_id": 85,
      "datasource": "VegBank",
      "dataset": "Glacier National Park",
      "dataowner": "Steve Cooper",
      "latitude": "48.506137075",
      "longitude": "-113.369232885",
      "date_collected": "2000-08-17",
      "scrubbed_genus": "Abies",
      "scrubbed_species_binomial": "Abies lasiocarpa"
    },
    {
      "taxonobservation_id": 37449270,
      "datasource_id": 85,
      "datasource": "VegBank",
      "dataset": "Glacier National Park",
      "dataowner": "Steve Cooper",
      "latitude": "48.576218428",
      "longitude": "-113.826884591",
      "date_collected": "2000-08-02",
      "scrubbed_genus": "Abies",
      "scrubbed_species_binomial": "Abies lasiocarpa"
    }
  ],
  "error": null
}

GET https://bienapi.xyz/occurrence/genus/

Query Parameters

Parameter Default Description
limit 10 number of results to return (max: 1000)
offset 0 record number to start at
genus NULL a genus name (e.g., Pinus)

Occurrences: family

Extract occurrence data for a given species

require 'faraday'

con = Faraday.new(url: "https://bienapi.xyz")
con.headers[:authorization] = ENV["BIEN_API_KEY"]
res = con.get '/occurrence/family', {:family => "Pinaceae"}
res.body
curl -H 'Authorization: '"$BIEN_API_KEY"'' \
  "https://bienapi.xyz/occurrence/family?family=Pinaceae" | jq .
library(crul)
auth <- list(Authorization = Sys.getenv('BIEN_API_KEY'))
con <- HttpClient$new("https://bienapi.xyz", headers = auth)
con$get("occurrence/family", query = list(family = "Pinaceae"))

The above command returns JSON structured like this:

{
  "count": null,
  "returned": 2,
  "data": [
    {
      "taxonobservation_id": 53172406,
      "datasource_id": 21,
      "datasource": "VegBank",
      "dataset": "Southwest GAP, Nevada",
      "dataowner": "Lisa Hahn",
      "latitude": null,
      "longitude": null,
      "custodial_institution_codes": null,
      "collection_code": null,
      "date_collected": "2002-09-18",
      "scrubbed_family": "Pinaceae",
      "scrubbed_species_binomial": "Pinus flexilis"
    },
    {
      "taxonobservation_id": 57033225,
      "datasource_id": 65,
      "datasource": "FIA",
      "dataset": "U.S. Forest Inventory and Analysis (FIA) National Program",
      "dataowner": "Greg Reams",
      "latitude": null,
      "longitude": null,
      "custodial_institution_codes": null,
      "collection_code": null,
      "date_collected": "2004-06-18",
      "scrubbed_family": "Pinaceae",
      "scrubbed_species_binomial": "Pinus monophylla"
    }
  ],
  "error": null
}

GET https://bienapi.xyz/occurrence/family/

Query Parameters

Parameter Default Description
limit 10 number of results to return (max: 1000)
offset 0 record number to start at
family NULL a family name (e.g. Pinaceae)

Taxonomy

Taxonomy: species

Extract taxonomy data for a species

require 'faraday'

con = Faraday.new(url: "https://bienapi.xyz")
con.headers[:authorization] = ENV["BIEN_API_KEY"]
res = con.get '/taxonomy/species', {:species => "Pinus contorta"}
res.body
curl -H 'Authorization: '"$BIEN_API_KEY"'' \
  "https://bienapi.xyz/taxonomy/species?species=Pinus%20contorta" | jq .
library(crul)
auth <- list(Authorization = Sys.getenv('BIEN_API_KEY'))
con <- HttpClient$new("https://bienapi.xyz", headers = auth)
con$get("taxonomy/species", query = list(species = "Pinus contorta"))

The above command returns JSON structured like this:

{
  "count": 20,
  "returned": 10,
  "data": [
    {
      "bien_taxonomy_id": 133727,
      "higher_plant_group": "gymnosperms (conifers)",
      "scrubbed_taxonomic_status": "Accepted",
      "scrubbed_family": "Pinaceae",
      "scrubbed_genus": "Pinus",
      "scrubbed_species_binomial": "Pinus contorta",
      "scrubbed_author": "(Balf.) Engelm.",
      "taxon_order": "Pinales",
      "taxon_class": "Equisetopsida"
    },
    {
      "bien_taxonomy_id": 540039,
      "higher_plant_group": "gymnosperms (conifers)",
      "scrubbed_taxonomic_status": "Accepted",
      "scrubbed_family": "Pinaceae",
      "scrubbed_genus": "Pinus",
      "scrubbed_species_binomial": "Pinus contorta",
      "scrubbed_author": "(Balf.) Engelm.",
      "taxon_order": "Pinales",
      "taxon_class": "Equisetopsida"
    }
  ],
  "error": null
}

GET https://bienapi.xyz/taxonomy/species/

Query Parameters

Parameter Default Description
limit 10 number of results to return (max: 1000)
offset 0 record number to start at
species NULL a species name (binomial: "genus epithet")

Taxonomy: genus

Extract taxonomy data for a genus

require 'faraday'

con = Faraday.new(url: "https://bienapi.xyz")
con.headers[:authorization] = ENV["BIEN_API_KEY"]
res = con.get '/taxonomy/genus', {:genus => "Carnegiea"}
res.body
curl -H 'Authorization: '"$BIEN_API_KEY"'' \
  "https://bienapi.xyz/taxonomy/genus?genus=Carnegiea" | jq .
library(crul)
auth <- list(Authorization = Sys.getenv('BIEN_API_KEY'))
con <- HttpClient$new("https://bienapi.xyz", headers = auth)
con$get("taxonomy/genus", query = list(genus = "Carnegiea"))

The above command returns JSON structured like this:

{
  "count": 3,
  "returned": 3,
  "data": [
    {
      "bien_taxonomy_id": 191125,
      "higher_plant_group": "flowering plants",
      "superorder": "Caryophyllanae",
      "scrubbed_taxonomic_status": "Accepted",
      "scrubbed_family": "Cactaceae",
      "scrubbed_genus": "Carnegiea",
      "scrubbed_species_binomial": "Carnegiea gigantea",
      "scrubbed_author": "(Engelm.) Britton & Rose",
      "taxon_order": "Caryophyllales",
      "taxon_class": "Equisetopsida"
    },
    {
      "bien_taxonomy_id": 338519,
      "higher_plant_group": "flowering plants",
      "superorder": "Caryophyllanae",
      "scrubbed_taxonomic_status": "Accepted",
      "scrubbed_family": "Cactaceae",
      "scrubbed_genus": "Carnegiea",
      "scrubbed_species_binomial": "Carnegiea gigantea",
      "scrubbed_author": "(Engelm.) Britton & Rose",
      "taxon_order": "Caryophyllales",
      "taxon_class": "Equisetopsida"
    }
  ],
  "error": null
}

GET https://bienapi.xyz/taxonomy/genus/

Query Parameters

Parameter Default Description
limit 10 number of results to return (max: 1000)
offset 0 record number to start at
genus NULL a genus name (e.g., "Pinus")

Taxonomy: family

Extract taxonomy data for a family

require 'faraday'

con = Faraday.new(url: "https://bienapi.xyz")
con.headers[:authorization] = ENV["BIEN_API_KEY"]
res = con.get '/taxonomy/family', {:family => "Cactaceae"}
res.body
curl -H 'Authorization: '"$BIEN_API_KEY"'' \
  "https://bienapi.xyz/taxonomy/family?family=Cactaceae" | jq .
library(crul)
auth <- list(Authorization = Sys.getenv('BIEN_API_KEY'))
con <- HttpClient$new("https://bienapi.xyz", headers = auth)
con$get("taxonomy/family", query = list(family = "Cactaceae"))

The above command returns JSON structured like this:

{
  "count": 6013,
  "returned": 10,
  "data": [
    {
      "bien_taxonomy_id": 781819,
      "higher_plant_group": "flowering plants",
      "superorder": "Caryophyllanae",
      "scrubbed_taxonomic_status": "Accepted",
      "scrubbed_family": "Cactaceae",
      "scrubbed_genus": "Acanthocalycium",
      "scrubbed_species_binomial": "Acanthocalycium ferrarii",
      "scrubbed_author": "Rausch",
      "taxon_order": "Caryophyllales",
      "taxon_class": "Equisetopsida"
    },
    {
      "bien_taxonomy_id": 762614,
      "higher_plant_group": "flowering plants",
      "superorder": "Caryophyllanae",
      "scrubbed_taxonomic_status": "Accepted",
      "scrubbed_family": "Cactaceae",
      "scrubbed_genus": "Acanthocalycium",
      "scrubbed_species_binomial": "Acanthocalycium klimpelianum",
      "scrubbed_author": "Backeb.",
      "taxon_order": "Caryophyllales",
      "taxon_class": "Equisetopsida"
    }
  ],
  "error": null
}

GET https://bienapi.xyz/taxonomy/family/

Query Parameters

Parameter Default Description
limit 10 number of results to return (max: 1000)
offset 0 record number to start at
family NULL a family name (e.g., "Cactaceae")

Citations

Citations: traits

Extract citation data for a trait

require 'faraday'

con = Faraday.new(url: "https://bienapi.xyz")
con.headers[:authorization] = ENV["BIEN_API_KEY"]
res = con.get '/meta/citations/traits/20024404/'
res.body
curl -H 'Authorization: '"$BIEN_API_KEY"'' \
  "https://bienapi.xyz/meta/citations/traits/20024404/" | jq .
library(crul)
auth <- list(Authorization = Sys.getenv('BIEN_API_KEY'))
con <- HttpClient$new("https://bienapi.xyz", headers = auth)
con$get("/meta/citations/traits/20024404/")

The above command returns JSON structured like this:

{
  "data": [
    {
      "id": null,
      "source": null,
      "url_source": null,
      "source_citation": null,
      "access": "public",
      "project_pi": "Greg Reams",
      "project_pi_contact": null,
      "citation_bibtex": "\"@MISC{noauthor_2013-mm,\n  title        = \"Forest Inventory and Analysis National Program\",\n  year         =  2013,\n  howpublished = \"\\url{http://www.fia.fs.fed.us/}\",\n  note         = \"Accessed: 2013-1-19\"\n}\""
    }
  ],
  "error": null
}

GET https://bienapi.xyz/meta/citations/traits/:id/

Citations: occurrences

Extract citation data for an occurrence

require 'faraday'

con = Faraday.new(url: "https://bienapi.xyz")
con.headers[:authorization] = ENV["BIEN_API_KEY"]
res = con.get '/meta/citations/occurrence/22/'
res.body
curl -H 'Authorization: '"$BIEN_API_KEY"'' \
  "https://bienapi.xyz/meta/citations/occurrence/22/" | jq .
library(crul)
auth <- list(Authorization = Sys.getenv('BIEN_API_KEY'))
con <- HttpClient$new("https://bienapi.xyz", headers = auth)
con$get("/meta/citations/occurrence/22/")

The above command returns JSON structured like this:

{
  "data": [
    {
      "observation_type": "plot",
      "datasource_id": 22,
      "source_name": "Badlands National Park",
      "source_fullname": "Badlands National Park",
      "source_type": "data owner",
      "proximate_provider_name": "VegBank",
      "proximate_provider_datasource_id": 1439,
      "primary_contact_firstname": "Jim",
      "primary_contact_lastname": "Von Low",
      "access_level": "public",
      "locality_error_added": true,
      "locality_error_details": "Reduced precision, selected plots only. Coordinate precision as been reduced to protect endangered species and/or hide locality of private land. Reduction in precision for each plot, if any, is indicated in column coord_uncertainty_m"
    },
    {
      "observation_type": "plot",
      "datasource_id": 1439,
      "source_name": "VegBank",
      "source_type": "proximate provider",
      "proximate_provider_name": "VegBank",
      "proximate_provider_datasource_id": 1439,
      "source_url": "http://vegbank.org/",
      "source_citation": "\"@ARTICLE{Peet2012-qw,\n title = \"{VegBank}: a permanent, open-access archive for vegetation plot\n data\",\n author = \"Peet, Robert K and Lee, Michael T and Jennings, Michael D and\n Faber-Langendoen, Don\",\n journal = \"Biodivers. Ecol.\",\n volume = 4,\n pages = \"233--241\",\n year = 2012\n}\"",
      "access_conditions": "acknowledge",
      "access_level": "public",
      "locality_error_added": false,
      "locality_error_details": "Reduced precision, selected plots only. Coordinate precision as been reduced to protect endangered species and/or hide locality of private land. Reduction in precision for each plot, if any, is indicated in column coord_uncertainty_m"
    }
  ],
  "error": null
}

GET https://bienapi.xyz/meta/citations/occurrence/:id/

Meta

Meta: version

Get current BIEN database version and release date

require 'faraday'

con = Faraday.new(url: "https://bienapi.xyz")
con.headers[:authorization] = ENV["BIEN_API_KEY"]
res = con.get '/meta/version/'
res.body
curl -H 'Authorization: '"$BIEN_API_KEY"'' \
  "https://bienapi.xyz/meta/version/" | jq .
library(crul)
auth <- list(Authorization = Sys.getenv('BIEN_API_KEY'))
con <- HttpClient$new("https://bienapi.xyz", headers = auth)
con$get("/meta/version/")

The above command returns JSON structured like this:

{
  "data": [
    {
      "bien_metadata_id": null,
      "db_version": "4.1.1",
      "db_release_date": "2018-12-06"
    }
  ],
  "error": null
}

GET https://bienapi.xyz/meta/version/

Meta: political names

List political divisions and associated geonames codes.

require 'faraday'

con = Faraday.new(url: "https://bienapi.xyz")
con.headers[:authorization] = ENV["BIEN_API_KEY"]
res = con.get '/meta/politicalnames/'
res.body
curl -H 'Authorization: '"$BIEN_API_KEY"'' \
  "https://bienapi.xyz/meta/politicalnames/" | jq .
library(crul)
auth <- list(Authorization = Sys.getenv('BIEN_API_KEY'))
con <- HttpClient$new("https://bienapi.xyz", headers = auth)
con$get("/meta/politicalnames/")

The above command returns JSON structured like this:

{
  "count": 43624,
  "returned": 10,
  "data": [
    {
      "county_parish_id": null,
      "country": "Romania",
      "state_province": "Olt",
      "state_province_ascii": "Olt",
      "country.code": 798549,
      "state.code": "29"
    },
    {
      "county_parish_id": null,
      "country": "Romania",
      "state_province": "Judeţul Maramureş",
      "state_province_ascii": "Judetul Maramures",
      "country.code": 798549,
      "state.code": "25"
    }
  ],
  "error": null
}

GET https://bienapi.xyz/meta/politicalnames/

Phylogeny

Download BIEN phylogenies

require 'faraday'

con = Faraday.new(url: "https://bienapi.xyz")
con.headers[:authorization] = ENV["BIEN_API_KEY"]
res = con.get '/phylogeny', {:type => "conservative"}
res.body
curl -H 'Authorization: '"$BIEN_API_KEY"'' \
  "https://bienapi.xyz/phylogeny?type=conservative" | jq .
library(crul)
auth <- list(Authorization = Sys.getenv('BIEN_API_KEY'))
con <- HttpClient$new("https://bienapi.xyz", headers = auth)
con$get("phylogeny", query = list(type = "conservative"))

The above command returns JSON structured like this:

{
  "count": 1,
  "returned": 1,
  "data": [
    {
      "phylogeny_id": 101,
      "phylogeny_version": "BIEN_2016_conservative",
      "replicate": null,
      "filename": "bien_conservative_phy.tre",
      "citation": "Enquist, B.J., Sandel, B., Boyle, B., Donoghue II, J.C., Regetz, J., Svenning, J.C., McGill, B.J., Peet, R.K., Jorgensen, P.M., Condit, R., Thiers, B., Schildhauer, M., Smith, S.A., Hinchliff, C.E., Wiser, S.K., Violle, C., äÌmov·, I., Spencer, N., Dolins, S., Morueta-Holme, N., Marcuse-Kubitza, A., Kraft, N.J.B., Ott, J.E., Andelman, S., ter Steege, H., Phillips, O., Sloat, L.L., Narro, M.L., Casler, N., Guaderama, D.,  Merow, C., Maitner, B.S. (in prep) A general signature of taxonomic and phylogenetic diversity across the Land Plants of the New World",
      "phylogeny": "(((Haplomitrium_blumei:644.869922,Apotreubia_nana:644.869922):20.905451,..."
    }
  ],
  "error": null
}

GET https://bienapi.xyz/phylogeny/

Query Parameters

Parameter Default Description
type "conservative" the type of phylogeny, conservative or complete

Errors

BIEN API uses the following error codes:

Error Code Meaning
400 Bad Request -- Your request is invalid. Check your request.
401 Unauthorized -- Your API key is invalid or you have not supplied a key.
404 Not Found -- The specified route could not be found.
405 Method Not Allowed -- You used an invalid HTTP method.
500 Internal Server Error -- We had a problem with our server. Try again later.
503 Service Unavailable -- We're temporarily offline for maintenance. Please try again later.

If you're not sure what to do, open an issue.