BCI Json Service

Note that this service is still experimental.

This is a simple service to provide access to BCI data as Javascript Object Notation (JSON). The endpoint for the service is: http://biocol.org/json

Please raise issues and suggestions on the Google Group.

There are two methods you can call on this service

Fetch

Simply pass this script between 1 and 100 BCI LSIDs as a space delimited list in the 'lsid' parameter and the script will return an array of JavaScript objects each of which represents a collections community record in the database. Each object will have around 30 properties with self explanatory names. The list of properties is given in the table below. Your code should handle nulls and missing properties as the list may change. Guaranteed properties are 'lsid', 'name' and 'url' (which is the human readable page for the collection on BCI).

The LSIDs can be passed as part of the URL path, in the query string of the URL or as a POST variable.

e.g. http://biocol.org/json/fetch/lsid/urn:lsid:biocol.org:col:15670 will return the record for the Royal Botanic Garden Edinburgh.

http://biocol.org/json/fetch?lsid=urn:lsid:biocol.org:col:15670 is equivalent

http://biocol.org/json/fetch?lsid=urn:lsid:biocol.org:col:15670+urn:lsid:biocol.org:col:15763 will return Edinburgh and Paris.

To pass larger numbers of LSIDs (up to 100) it would obviously be better to use a POST request.

By default the results are wrapped in a callback call: "callback([...])". You can change the name of this call by passing the callback parameter. e.g.

http://biocol.org/json/fetch/callback/mycallback/lsid/urn:lsid:biocol.org:col:15670

http://biocol.org/json/fetch?callback=mycallback&lsid=urn:lsid:biocol.org:col:15670

Search

The JSON search method allows the construction of complex searches. The parameter encoding and return type are the same as for the Fetch method above.

Simple Queries

To search for records that have a particular value in a particular field simply pass that field in the query parameter e.g. http://biocol.org/json/search?code=CAS will return the community records where the code field contains 'CAS'. For string fields these comparisons are case insensitive.

Multiple parameters are ANDed together so http://biocol.org/json/search?code=CAS&kind=herbarium will return community records for collections that have the code = 'CAS' AND kind = 'herbarium'.

Like Queries

For fields of type string you can include % signs in the parameter value and an SQL LIKE comparison will be carried out rather than an equals. So http://biocol.org/json/search?code=CA%&kind=herbarium will return the community records of kind = herbarium and codes that start with CA. Like queries are not carried out on fields of type number or date

Negating String Queries

Both Like and Equality string comparisons can be negated by starting the value with a '-' (minus sign). So http://biocol.org/json/search?code=CA%&kind=-herbarium will return community records for collections that have codes that start with CA but are not of kind = herbarium.

Greater-Than / Less-Than Numeric and Date Queries

For fields of type number or date you can start the parameter value with a < or >. So http://biocol.org/json/search?founded_year=<1900 will return the community records with a founding year less than 1900

Repeating Parameters

You can repeat the same parameter in a search but you must append square brackets to the end of the parameter name if you do so (PHP style). So http://biocol.org/json/search?founded_year[]=<1900&founded_year[]=>1890 will return community records for collections founded after 1890 but before 1900. A similar technique could be used for lat/long bounding boxes.

Limit and Offset = Paging

The maximum number of results returned is 50. If there are more than 50 you will get the first 50 and no warning that there are more. You can limit the results to less that 50 by specifying the parameter limit= as a number less than 50. You can specify and offset to say what index you would like your results to start. So http://biocol.org/json/search?founded_year[]=<1900&founded_year[]=>1890&limit=10&offset=10 will return the second 'page' of ten results.

Ordering

Paging is pretty useless unless the results can be guaranteed to come in a particular order so we have the ability to specify an order-by parameter so http://biocol.org/json/search?founded_year[]=<1900&founded_year[]=>1890&limit=10&offset=10&order-by=founded_year,name will order the results by founded_year then name. Prepending the field name with a '-' (minus sign) will cause the order to be descending. Ordering depends on the data type of the field. Strings are alphabetical, numbers numeric and dates by date!

Data Source

By default all queries are run against the community records as these are often the most complete in terms of BCI data and every collection has a community editable record. If you would like to query collection records from a particular source you can specify a 'source' parameter with one of the following values: ih for Index Herbariorum, iscw for Insect and Spider Collections of the World or Bioreposit for BioRepositories.org records. So http://biocol.org/json/search?code=CAS&source=ih will return only records from Index Herbariorum with code CAS

Table of Properties

        <script type="text/javascript" charset="utf-8" src="http://biocol.org/js/BCILinks.js"></script>
    

        <body onload="BCILinks.parseLinks()">
    

        <a class="BCI-Code-Link">E</a>
        <a class="BCI-Name-Link">Royal Botanic Garden Edinburgh Herbarium</a>
        <a class="BCI-LSID-Link">urn:lsid:biocol.org:col:15670</a>
    

        <body onload="BCILinks.debug = true; BCILinks.parseLinks()">