Web service API v1.0

Synopsis

The goal of this API is to facilitate access to speciesLink data by other applications.

Calls are made through HTTP GET method, passing optional parameters as part of the query string. Responses are in JSON format.

This service provides access to both provider metadata, such as collection name and type, as well as biodiversity records.

Access to the API is open to anyone, but requires an API key that has to be provided as an "apikey" parameter in every service call. Manage your API keys here. For clarity, the "apikey" parameter is omitted in the URLs displayed for all examples below.

Metadata

Basic metadata, such as available languages, institution types, collection types and networks, can be accessed with the following URL:

https://specieslink.net/ws/1.0/info

To get information only in a particular language use the "lang" parameter. Available languages can also be found in the response:

https://specieslink.net/ws/1.0/info?lang=pt-br

Listing all collections and institutions

To get all participant collections and institutions hierarchically:

https://specieslink.net/ws/1.0/participants

Getting data about a single institution

To get data about a specific institution returning content in all available languages:

• Using an acronym:
  https://specieslink.net/ws/1.0/ins/USP/
• Using an id:
  https://specieslink.net/ws/1.0/ins/393/

To get data about a specific institution returning content only in a specific language:

• Using an acronym:
  https://specieslink.net/ws/1.0/ins/USP/?lang=en
• Using an id:
  https://specieslink.net/ws/1.0/ins/393/?lang=pt-br

Getting data about a single collection

A similar approach can be used to get data about a specific collection:

• Using an acronym:
  https://specieslink.net/ws/1.0/col/ESA/
• Using an id:
  https://specieslink.net/ws/1.0/col/8/?lang=pt-br

Getting data about a single dataset

Each collection may provide multiple datasets to speciesLink. To get data about a specific dataset, use the dataset id:

https://specieslink.net/ws/1.0/dts/8/

Biodiversity records

Biodiversity records can be searched returning either individual records or clusters of records grouped by a specified criterion. In both cases, there is a common set of filters that can be used, but there are also more specific parameters that only apply on each case. Responses are in GeoJSON format: points for individual records, multipolygons for records grouped by geohash. By default, individual records are returned. The following base URL is shared in both cases:

https://specieslink.net/ws/1.0/search

Common filters

The following searchable fields can be used as part of the query string. Parameter names are case-insensitive.

→ Accepts multiple comma-separated values.

Examples:

• Getting records of a particular species:
  https://specieslink.net/ws/1.0/search?scientificname=araucaria+angustifolia
• Getting records collected in a specific county on a specific year:
  https://specieslink.net/ws/1.0/search?county=cajuru&yearcolledted=2010
• Getting records given a barcode list:
  https://specieslink.net/ws/1.0/search?barcode=UEC180250,UEC006758

Special filters

→ Accepts multiple comma-separated values.

Pagination

Two parameters can be used for pagination, and they are only available when handling individual records:

offset: Index of the first record to be returned, starting at zero.

limit: Number of records to be returned. Default: 200. Maximum: 5000.

Every page includes an attribute *numberReturned* that will always be less than or equals the *limit* being used. Additionally, the first page always includes the attribute *numberMatched* to indicate the total number of records matched by the query. If a client is only interested in the total number of matched records, it's possible to set limit = 0 in the request to avoid streaming results.

Examples:

• Paginating over records of a specific family, starting with the first 30 records:
  https://specieslink.net/ws/1.0/search?family=eriocaulaceae&offset=0&limit=30

Fields to be returned

In the previous examples, you may have noticed that a standard set of fields is always returned for each individual record. The following parameter can be used to choose between different sets of fields to be returned according to the next table. This parameter only applies when returning individual records. For each record, some fields may not be returned if there is no data associated.

output: Specifies which set of fields should be returned. Default: "dwc".

Grouping records

Records can be grouped by a specified criterion. Currently this is only available for geohash, allowing mapping applications to retrieve results grouped by larger pixels rather than fetching millions of individual records. When records are grouped by geohash, a set of square multipolygons is returned in GeoJSON, including the total number of records per geohash, so that heat maps can be generated.

groupby: Criterion by which records are grouped. Available options: geohash.

precision: Auxiliary parameter when records are grouped by geohash, specifying the geohash precision in kilometers. Default: 500km.

above: Auxiliary parameter when records are grouped by geohash, indicating that aggregation should only take place when the number of matching records is above the specified number. Otherwise, response will fall back to returning individual records. Use either a positive number or the keyword "max_limit" to indicate the maximum number of records that can be returned by the service through pagination. When specifying a number, it cannot exceed the maximum number of records returned by the service, otherwise it will be automatically adjusted. This parameter can be particularly useful for mapping applications that need to switch between displaying individual records or geohash aggregations, depending on the number of matching records, sparing clients from implementing an extra service call to get the number of matching records followed by additional logic to build the request and also avoiding to handle pagination.

Examples:

• All records grouped by geohash inside a bounding box:
  https://specieslink.net/ws/1.0/search?groupby=geohash&precision=300&bbox=-71.11992+-9.35051+-49.29183+2.56214

Leaflet example

Since specieslink contains millions of records, displaying them on a map requires some special approach. The following example makes service calls using the "groupby" parameter associated with the "above" parameter, so that results are automatically aggregated if the number of matching records exceeds, in this case, 1k records. Every call always includes a bounding box filter, restricting search to the visible area. The map is also refreshed after each pan or zoom. A simple approximation is used to adjust geohash precision according to the map area.

    var mymap = L.map('map');

    // set map center with zoom level
    mymap.setView(new L.LatLng(-23.36, -46.84), 5);

    // add openstreetmap layer
    L.tileLayer('https://tile.openstreetmap.org/{z}/{x}/{y}.png', {
        maxZoom: 19,
        attribution: '&copy; <a href="http://www.openstreetmap.org/copyright">OpenStreetMap</a>'
    }).addTo(mymap);

    // function to fetch remote json data given an url
    function getJSON(url, param) {
        var xhttp = new XMLHttpRequest();
        xhttp.open("GET", url, false);
        xhttp.setRequestHeader("Content-type", "application/x-www-form-urlencoded");
        xhttp.send(param);
        eval("my_points_layer = " + xhttp.responseText);
        return my_points_layer
    }
    
    var specieslink_layer = null;

    // function to build specieslink web service url
    function get_specieslink_url(){
        // estimate precision in km so that we get ~500 cells displayed on the map with aggregation
        var diagonal_in_km = mymap.distance(mymap.getBounds().getSouthWest(), mymap.getBounds().getNorthEast())/1000;
        var visible_area = (diagonal_in_km*diagonal_in_km)/2;
        var cell_area = visible_area/500;
        var precision = Math.round(Math.sqrt(cell_area));
        // only aggregate results when displaying more than 1k records
        return 'https://specieslink.net/ws/1.0/search?apikey=YOUR_API_KEY&groupby=geohash&precision='+precision+'&above=1000'
            +'&bbox='
        +mymap.getBounds().getSouthWest().lng+'+'
        +mymap.getBounds().getSouthWest().lat+'+'
        +mymap.getBounds().getNorthEast().lng+'+'
        +mymap.getBounds().getNorthEast().lat;
    }

    function refresh_specieslink_data() {
        if (specieslink_layer !== null) {
            mymap.removeLayer(specieslink_layer)
        }
        var url = get_specieslink_url();
        //console.log(url);
        var geojson_data = getJSON(url);
        var style = {}
        // use different style when results are aggregated as MultiPolygons
        if (geojson_data.hasOwnProperty("features") &&
            geojson_data.features.length > 0 &&
            geojson_data.features[0].hasOwnProperty("geometry") &&
            geojson_data.features[0].geometry.type == "MultiPolygon") {
            style = { style: function (feature) {
                                 var num_points = feature.properties.num_points;
                                 // set color according to the number of aggregated points
                                 switch (true) {
                                     case num_points < 11  : return {color: "#D88A01"};
                                     case num_points < 51  : return {color: "#EA8015"};
                                     case num_points < 101 : return {color: "#EA5615"};
                                     case num_points < 501 : return {color: "#EA2C15"};
                                     default               : return {color: "#BC2110"};
                                  }
                             }
                    };
        }
        specieslink_layer = L.geoJson(geojson_data, style);
        specieslink_layer.addTo(mymap);
    }

    // load data for the first time
    refresh_specieslink_data()

    // refresh data after each pan or zoom
    mymap.on('moveend', refresh_specieslink_data);

---

Additional references

+- available collections

+- available institutions