Notice:

The BISON Web Service APIs have been updated. A summary of the enhancements to the APIs include:

  • The OGC WMS API includes changes to parameter values and additional parameters.
  • The OpenSearch API includes changes to parameter values and additional parameters.
  • The Solr API schema has changed; including modified parameter names and new parameters.

BISON supports several data interchange formats to enable developers to write custom applications. The BISON and Solr search APIs support JavaScript Object Notation (JSON) and JSON with Padding (JSONP). The Web Mapping Services support Portable Network Graphics (PNG) . The web services APIs (OpenSearch & WMS) do not provide the ability to disambiguate species as does the BISON web based UI. When homonyms (names that map to multiple TSNs) exist for either a common name or scientific name OpenSearch or WMS search, a combined query is performed (e.g. Ficus maps to TSNs 73159 and 19081). The resulting combined web service query will return results that include either TSN. Example applications have been written using OpenLayers, and HTML 5 and we are working on mobile applications that will be available shortly.

BISON Search:

BISON can be searched using an OpenSearch API. Here's an example of how to pass a search term to the BISON Service

https://bison.usgs.gov/api/search.json?species=Bison bison&type=scientific_name&start=0&count=1

Using the 'search.json?' as in the above example will provide a response formatted as JSON. Using 'search.jsonp?' with the callback parameter will provide a response formatted as JSONP. The response will include the number of occurrences in each county and state in the United States and Canada. It will also return a legend and the exact location of the first occurrence in Solr. This API is limited to returning a maximum of 1000 records at a time. If larger sets are needed we recommend using the Solr API with pagination.

Search Parameters:

species = Specifies the species search term. Example: Bison bison
type = Specifies the species name type (REQUIRED, if parameter species is used). Example: scientific_name or common_name .
itis = Turns on itis enabled search. Example: itis .
tsn = Specifies the TSN to query by. Example: 162003
state = Specifies the textual state name to geographically constrain the search. Example: Tennessee .
countyFips = Specifies the county fips code to geographically constrain the search to one county. Example: 49015 .
aoi = Specifies a WKT (Well-Known Text) polygon to geographically constrain the search. Example:

POLYGON((-111.06360117772908 38.84001566645886,-110.80542246679359 39.37707771107983,-110.20117441992392 39.17722368276862,-110.20666758398464 38.90844075244811,-110.63513438085685 38.67724220095734,-111.06360117772908 38.84001566645886)),

which calls up the occurrences within the specified area.
aoibbox = Specifies a four-sided bounding box to geographically constrain the search using format:

minx,miny,maxx,maxy

. The coordinates are Spherical Mercator with a datum of WGS84. Example:

-111.31079356054,38.814339278134,-110.57470957617,39.215537729772

start = Specifies the offset position for a query enabling pagination of the result set. Default: 0 .
count = Specifies the total number of results to return. An error will be returned if the maximum is exceeded. Default: 25 Maximum: 500 .
callback = Specifies the function to wrap the JSON response in to produce JSONP. Only relevant when using the 'search.jsonp?' target.
params = Supports extended query parameters. See the params section for details.
A response to a BISON Search may be in JSON format. When the information is unavailable in the record the field and data are not returned to facilitate fast response times. An Example Response follows: 

{
	"total":0,                       // Total # of Results found
	"georeferenced":0,               // Total # with lat/lon values
	"species":"species name",        // (Optional) Species specified
	"occurrences":{"legend":{}},     // Information pertaining to point statistics
	"counties":{"total":0},          // Information pertaining to county statistics (results per county)
	"states":{"total":0},            // Information pertaining to state statistics (results per state)
	"searchTime":3063,               // Search time on server in milliseconds
	"type":"scientific_name",        // Included only when species was specified in the search
	"offset":0,                      // the offset from the beginning of the search allowing the 
                                         //     result set to be paginated.
	"data":[                         // The data set returned
		{
			"occurrenceID":"14385",                           // The ID of the record
			"geo":"Yes",                            // Is the record GeoReferenced?
			"basis":"Observation",                  // Basis of record type
			"name":"Baeolophus bicolor",            // Scientific name
			"decimalLatitude":"23.5473",                   // The decimal latitude
			"decimalLongitude":"-34.5434",                 // The decimal longitude
			"common_name":"Tufted Titmouse",        // Common name(s) -- comma separated
			"provider":"Avian Knowledge Network"    // Data provider
		}, ....
	],                      
	"itemsPerPage":1                 // The number of items in a page in a paginated response
}

Web Map Service (WMS):

BISON WMS end points can be used to render BISON data in a mapping application such as OpenLayers. There are two WMS endpoints in BISON. The Heatmap WMS simply returns a heatmap of the search results. The Species WMS endpoint returns a species occurrence map. At the moment, the GetCapabilities WMS is not supported due to the non-standard nature of this WMS implementation. The Endpoint URLs are as follows:

Heatmap WMS: https://bison.usgs.gov/api/heatmap/wms?

Species Occurrence WMS: https://bison.usgs.gov/api/wms?

Here's an example of a WMS request to the BISON API Service

https://bison.usgs.gov/api/wms?LAYERS=species&species=Pica pica&type=scientific_name&TRANSPARENT=true... &FORMAT=image%2Fpng&SERVICE=WMS&VERSION=1.1.1&REQUEST=GetMap&STYLES=&SRS=EPSG%3A3857&BBOX=-20037508.34,-1.862645149231e-9,-5009377.085,15028131.255&WIDTH=512&HEIGHT=512

Possible Search Parameters:

REQUEST = Specifies the OGC request type. (REQUIRED) Example: GetMap . GetFeatureInfo and GetCapabilities are not supported at this time.
LAYERS = Specifies the WMS layer to return. (REQUIRED) For the occurrence WMS, use species . For the heatmap WMS, you can choose between county , and state .
TRANSPARENT = Specifies whether the image should be rendered in a transparent space. (REQUIRED) Example: true or false .
FORMAT = Specifies the image format to return in the WMS. (REQUIRED) Example: image/png .
SERVICE = Specifies the OGC service type. (REQUIRED) Example: WMS .
VERSION = Specifies the OGC service version. (REQUIRED) Example: 1.1.1 .
WIDTH = Specifies the width of the image in pixels.(REQUIRED) Example: 256 .
HEIGHT = Specifies the height of the image in pixels. (REQUIRED) Example: 256 .
BBOX = Specifies the bounding box (minx,maxx, miny, maxy) of the image to be rendered (REQUIRED). This is different than the polygon AOI since the AOI may span multiple images. Example:

-12366899.678594,4696291.0171875,-12210356.644688,4852834.0510937

Coordinates must be in Web Mercator (Spherical Mercator with WGS 1984 as the Datum).
SRS = Specifies spatial reference system of the image. (REQUIRED) The only supported value at this time is: EPSG:3857
species = Specifies the species search term. Example: Bison bison
type = Specifies name type (REQUIRED, if parameter species is used. Valid values are either scientific_name or common_name).
itis = Turns on itis enabled search. Example: itis .
tsn = Specifies the TSN to query by. Example: 180604 .
state = Specifies the textual state name to geographically constrain the search. Example: Tennessee .
countyFips = Specifies the county fips code to geographically constrain the search. Example: 49015 . Multiple counties are comma separated.
aoi = Specifies a WKT (Well-Known Text) polygon to geographically constrain the search. Example:

POLYGON((-111.06360117772908 38.84001566645886,-110.80542246679359 39.37707771107983,-110.20117441992392 39.17722368276862,-110.20666758398464 38.90844075244811,-110.63513438085685 38.67724220095734,-111.06360117772908 38.84001566645886)), which calls up the occurrences within specified area.

aoibbox = Specifies a four-sided bounding box to geographically constrain the search using format:

minx,miny,maxx,maxy

Example:

-111.31079356054,38.814339278134,-110.57470957617,39.215537729772

params = Supports extended query parameters. See the params section for details.

Extended 'params' argument for WMS and OpenSearch


Extended query attributes are accessible using the 'params' argument. This argument enables querying on some of the field described in the Solr section of this page. The query-able field include:

  • providerID
  • resourceID
  • basisOfRecord
  • catalogNumber
  • year
  • computedStateFips
  • hierarchy_homonym_string
  • TSNs
  • recordedBy
  • occurrenceID
  • collectorNumber
  • provider
  • ownerInstitutionCollectionCode
  • eventDate
  • providedScientificName
  • scientificName
  • ITISscientificName
  • providedCommonName
  • ITIScommonName
  • kingdom
  • ITIStsn
  • centroid
  • higherGeographyID
  • computedCountyFips
  • providedCounty
  • calculatedCounty
  • stateProvince
  • calculatedState
  • countryCode
For example, you may get results specifically for a provider or resource:
  • providerID:("318") Find the provider with ID 318.
    resourceID:("318,1902" "318,9151" ) Find all resources with id of '318,1902' OR '318,9151', with values separated by spaces.

Criterion may be combined using the semicolon (';') character, which translates to a logical AND operator. Note that field names and values are case sensitive.
  • params=providerID:("408" "432");resourceID("14027")

Many web browser will automatically handle encoding of the URL request, but some browsers (e.g. IE9) do not. In this case it is necessary to manually encode the URL:
  • params=resourceID%3A(%2214027%22+)%3B providerID%3A(%22408%22+)
The URI https://bison.usgs.gov/api/search.jsonp?params=resourceID%3A(%22318%2C1902%22+)%3BproviderID%3A(%22318%22+)%3BbasisOfRecord%3A(specimen) can be used display occurrences with Resource ID of '318,1902' and Provider ID of '318' and basisOfRecord as 'specimen'.
The URI https://bison.usgs.gov/api/search.jsonp?params=occurrenceID:(1033963806) will return the record with Occurrence ID 1033963806.
The URI 'https://bison.usgs.gov/api/wms?LAYERS=species&TRANSPARENT=true&FORMAT=image%2Fpng&SERVICE=WMS&VERSION=1.1.1&REQUEST=GetMap&STYLES=&TSN=174371&ITIS=itis&SRS=EPSG%3A3857&BBOX=-12664334.196143,3634261.2797526,-12276272.399098,4022323.0767977&WIDTH=256&HEIGHT=256&params=resourceID%3A(%22318%2C1902%22+)%3BproviderID%3A(%22318%22+)' will display a WMS provided png showing Bird occurrences with a Resource ID of '318,1902' and Provider ID of '318'.
The URI 'https://bison.usgs.gov/api/heatmap/wms?LAYERS=county&species=Buteo+jamaicensis&type=scientific_name&TRANSPARENT=true&FORMAT=image%2Fpng&SERVICE=WMS&VERSION=1.1.1&REQUEST=GetMap&STYLES=&SRS=EPSG%3A3857&BBOX=-8927745.4216059,4304416.2699315,-8438548.4717241,4793613.2198133&WIDTH=512&HEIGHT=512&PARAMS=providerID:(4%20305%20177%2018%20221%2027%2030%2031%20275%20395%2039%20143%20234%2049%20461%20410%20336%20407%2085%2095%20105%20108%20110%20377%20120%20220%20131%20104%20137%2083%2082%20149%20150%20151%20152%20155%20435%20160%20439)' will display a WMS provided png showing a heatmap of Buteo jamaicensis occurrences matching the specified Provider IDs.


REST API


Access to BISON page search results is provided via a REST (Representational State Transfer) API. The response provided by this API is the BISON search page showing the results of the query represented in the REST URL. The default REST search does not use ITIS taxonomy. Below are some samples.

The URI https://bison.usgs.gov/index.jsp?scientificName=Poa annua can be used display all of the bluegrasses.
The URI https://bison.usgs.gov/index.jsp?scientificName=poa cusickii will display Cusick's bluegrass.
The URI https://bison.usgs.gov/index.jsp?scientificName=Poa&ITIS=itis will display all of the bluegrass doing an ITIS enabled search.


Providers and Resources Identifiers


BISON allows users to access occurrence data based upon the providers and resources identifiers using unique stable identifiers. BISON has a REST API that allows users to query for information about providers and resources. Some sample URIs follow:

The URI https://bison.usgs.gov/api/providers/all can be used retrieve provider information as a JSON object.
The URI https://bison.usgs.gov/api/providers/details can retrieve information about both providers and resources as a JSON object.
The URI https://bison.usgs.gov/api/providers/{Provider Number}/resources can be used to retrieve information about the resources assigned to a particular provider. For example this URI will retrieve all of the resources from Provider 131 https://bison.usgs.gov/api/providers/131/resources.


Data Provider Statistics API

Download Last Year's Statistics API Archive
BISON exposes an API supporting access to Data Provider and Resource* based data access statistics. The BISON based UI for the Data Provider Statistics is accessible via a link on the Data Providers tab. The Statistics API is REST based and provides a JSON formatted response. Data Provider Statistics for data retrieval directly from the BISON Solr index are not currently available.
*A single Data Provider may contribute multiple data Resources.

The URI https://bison.usgs.gov/api/statistics may be used to retrieve all Data Provider accumulated statistics as a JSON object.
The URI https://bison.usgs.gov/api/statistics/all may also be used with the same effect.
The URI https://bison.usgs.gov/api/statistics/search may be used to retrieve Data Provider statistics for BISON searches as a JSON object.
The URI https://bison.usgs.gov/api/statistics/download may be used to retrieve Data Provider statistics for data downloads from BISON as a JSON object.
The URI https://bison.usgs.gov/api/statistics/wms may be used to retrieve Data Provider statistics for BISON OGC WMS tile requests as a JSON object.


Apache Solr API


BISON also has a Solr API supporting Apache Solr which can be accessed at https://bison.usgs.gov/solr/occurrences/select/?q=*:*. The database has been modified to be Darwin Core Compliant. To retrieve the first ten occurrence records from Solr you would need to type this query https://bison.usgs.gov/solr/occurrences/select/?q=*:* More information can be found about Solr on the Apache website. The Solr schema is defined below and does not support any native geospatial operators. BISON was written to optimize the performance of retrieving occurrence records, and after extensive design work, it was found that working with the raw spatial data and applying optimized mathematics was faster than Solr geospatial operators. For larger record set requests, we recommend using the BISON Solr API with pagination.

Most modern browsers will automatically URL encode white space and other special characters that you enter on the URL line. If you are calling Solr from javascript or another programming language you may be required to URL encode the query string. More information can be found about URL encoding in RFC-1738.

Occurrence record schema (Core)

Name Type Description
decimalLatitude sfloat Geographic coordinate that specifies the north south position of a location on the Earth surface.
decimalLongitude sfloat Geographic coordinate that specifies the east-west position of a location on the Earth surface.
year sint The year the collection was taken.
pointPath string A dynamic field that contains the location in longitude and latitude followed by the basis of record and an optional Geo (Spatial) precision. Geo (Spatial) precision is an added descriptor when the record is a county centroid.
providerID sint Unique identifier assigned by the Global Biodiversity Information Facility (GBIF) as we are working with them to make it persistent (stable) over time.
resourceID string A unique identifier that is a concatentation of the provider identifier and the resource id seperated by a comma.
basisOfRecord string One of these enumerated values: Observation, Germplasm, Fossil, Specimen, Literature, Unknown, or Living.
eventDate string The date when the occurrence was recorded.
verbatimEventDate string The original description of the date on which the observation or collection event occurred (Not currently available as a searchable field).
computedCountyFips string County FIPS code conforming to standard FIPS 6-4.
computedStateFips string County FIPS code conforming to standard FIPS 5-2.
scientificName string The Latin scientific name with rank indicators, authors and emendations removed. Referred to by GBIF as the canonical name.
hierarchy_homonym_string string A denormalized string of ITIS Taxonomic Identifiers (TSNs) representing the taxonomic classification hierarachy of the accepted or valid species name starting at kingdom. If the name is a taxonomic homonym more than one string is provided seperated by ';'.
TSNs string For each accepted or valid taxonomic name in ITIS that matches the current occurrence the TSN of the accepted or valid name is provided. If the name is a taxonmic homonym more than one TSN is provided.
recordedBy string Individual responsible for the scientific record.
occurrenceID string Non-persistent unique identifier.
catalogNumber string A string generally passed on from the original provider or assigned in some BISON provided data sets in collaboration with the provider. It usually appears as an integer but often includes text and symbols as well.
collectorNumber string An identifier given to the occurrence at the time it was recorded, such as a specimen collector's number. / "SJM030022".
provider Non-persistent unique identifier.
ownerInstitutionCollectionCode Name for the dataset, format = OwnerInstitution-Collection. / "USGS NAWQA BioData - Fish Occurrence Records"
providedScientificName string Full scientific name as provided in the dataset, with authorship and date information if known.
ITISscientificName string The current valid or accepted scientific name for a taxon, if available, according to the Integrated Taxonomic Information System (ITIS) / "Rhinella marina"
providedCommonName string A list (concatenated and separated) of the available vernacular species names. / "common shrew, Masked Shrew"
ITIScommonName string The common name(s) for a taxon, if available, according to the Integrated Taxonomic Information System (ITIS) / "Cane toad"
kingdom string From GBIF raw occurrence or BISON provider.
ITIStsn string Phase II: ITIS TSN corresponding to clean_provided_scientific_name. May be invalid,unaccepted. Calculated / "3250", "05713"
geodeticDatum string The ellipsoid, geodetic datum, or spatial reference system (SRS) upon which the geographic coordinates given in decimalLatitude and decimalLongitude as based. Leave blank if no lat/lon provided, unknown if unknown (Not currently available as a searchable field).
coordinatePrecision A decimal representation of the precision of the coordinates given in the decimalLatitude and decimalLongitude (Not currently available as a searchable field).
coordinateUncertaintyInMeters The horizontal distance (in meters) from the given decimalLatitude and decimalLongitude describing the smallest circle containing the whole of the Location (Not currently available as a searchable field).
verbatimLocality string The original description of the location at which the observation or collection event occurred (Not currently available as a searchable field).
mrgid string Numeric text string code or Marine Region Identifier for the U.S. Marine Exclusive Economic Zone (EEZ) value in the calculatedWaterbody field (Not currently available as a searchable field). / "8456000"
calculatedWaterbody string Standard name for the U.S. Marine Exclusive Economic Zone (EEZ) in which the observation or collection event occurred (Not currently available as a searchable field). / "US Pacific EEZ"
establishmentMeans string A code indicating the process by which the species became established at the location (AK=nonnative in Alaska, HI=nonnative in Hawaii, L48=nonnative in the 48 contiguous United States). / "AK", "HI", "L48"
verbatimElevation string The original description of the elevation (altitude, usually above sea level) of the Location (Not currently available as a searchable field).
verbatimDepth string The original description of the depth below the local surface (Not currently available as a searchable field).
centroid string Text string indicating that provided lat/lon point represents a polygon centroid. Text provides description of the centroid..
higherGeographyID string 5-digit numeric text string geographic code for the state-county combination provided by data provider. / "13029"
providedCounty Full county, parish, or organized borough name, as provided in the dataset. If provided, Verbatum State is required. Is not changed during data ingest. / "Fairfax"
calculatedCounty string Full county, parish, or organized borough name of the occurrence calculated. / "Fairfax"
stateProvince string Full name of state or territory of the occurrence, as provided in the dataset.
calculatedState string U.S. State or territory name calculated. / "Puerto Rico"
countryCode string The geographic location of the specific occurrence, expressed through a constrained vocabulary of countries using 2-letter ISO country code.
institutionID string The URL link to the provider of the data (Not currently available as a searchable field).
collectionID string URL link to the dataset . For BISON link to the IPT resource (Not currently available as a searchable field).
relatedResourceID string URL link to the occurrence record (where available). An identifier for a related resource (the object, rather than the subject of the relationship) (Not currently available as a searchable field).
thumbURL string URL link to a small version of a larger associatedMedia source file of the occurrence (Not currently available as a searchable field).
associatedMedia string URL identifier of media associated with the occurrence. Compatible formats of the URL's source file are any readable by a browser, such as jpg, png, gif, tif, mp3, wav, etc. If provided, is linked to a thumbnail image URL (Thumb URL) (Not currently available as a searchable field).
associatedReferences string A hyperlinked resource or reference associated with the occurrence, such as a sound or video file, pdf publication, or an html landing page with additional associated URLs (Not currently available as a searchable field).
generalComments string Free text field for comments that add pertinent information to the record but do not fall into available field categories (Not currently available as a searchable field).
license string A code or URL link to the Creative Commons license that applies to the species occurrence record (Not currently available as a searchable field). / "CC_BY_NC_4_0", "http://creativecommons.org/publicdomain/zero/1.0/legalcode"

Common Name Schema

The common name index URI is located here. It contains the common name from ITIS.

Scientific Name Schema

The scientific name index URI is located here. The complete set of scientific names in the occurrence data set plus the taxonomic hierarchy upwards.

Data Use Agreement

Any use of BISON web services automatically commits the user to acceptance of the Data Use Agreement.

Adapted from the Data Use Agreement of the Global Biodiversity Information Facility (GBIF).

Background

Biodiversity Information Serving Our Nation (BISON) is committed to providing free and open access to species occurrence data. Data currently available through BISON are provided through the Global Biodiversity Information Facility (GBIF). GBIF Participants who have signed the GBIF Memorandum of Understanding have expressed their willingness to make biodiversity data available through their nodes to foster scientific research development internationally and to support the public use of these data (see http://data.gbif.org/tutorial/datasharingagreement). GBIF data sharing should take place within a framework of due attribution. Therefore, using data available through BISON requires agreement with the following:

1. Data Use Agreements

The quality and completeness of data cannot be guaranteed. Users employ these data at their own risk. Users shall respect restrictions of access to sensitive data. In order to make attribution of use for owners of the data possible, the identifier of ownership of data must be retained with every data record. Users must publicly acknowledge, in conjunction with the use of the data, the data publishers whose biodiversity data they have used. Data publishers may require additional attribution of specific collections within their institution. Users must comply with additional terms and conditions of use set by the data publisher. Where these exist they will be available through the metadata associated with the data (see http://data.gbif.org/datasets/).

2. Citing Data

Use the following format to cite data retrieved from BISON:

[Data Provider or owner name]. [Resource or Dataset Name] published by [Data Provider name, address or affiliation(s)] (Accessed through Biodiversity Information Serving Our Nation (BISON), https://bison.usgs.gov, YYYY-MM-DD)

For example:
Field Museum of Natural History. U.S. Bird Occurrences published by Field Museum of Natural History, Museum of Vertebrate Zoology, University of Washington Burke Museum, and University of Turku (Accessed through Biodiversity Information Serving Our Nation (BISON), https://bison.usgs.gov, 2007-02-22)

Or

Gordon, J. U.S. Bird Occurrences published by Field Museum of Natural History, Museum of Vertebrate Zoology, University of Washington Burke Museum, and University of Turku (Accessed through Biodiversity Information Serving Our Nation (BISON), https://bison.usgs.gov, 2007-02-22)