NBN web services

Understanding and making the most of Web Services

Introduction

The NBN Web Services provide a flexible and powerful route to the 50 million plus British and Irish plant and animal records loaded onto the NBN Gateway.  They allow map images and data to be integrated into websites and online applications, giving rapid access to the most up-to-date biodiversity data on the NBN Gateway.

This article aims to do two things.  Firstly, to give you a good understanding of the key web services and their features by exploring different examples.  Secondly, it will provide high level guidance to help you get started and where to go for documentation, guidance and help.  To view more examples of the NBN’s web services in action go to our web services guide.  As you will see, the web services mimic many of the features available on the NBN Gateway website.

Species distributions

By far the most commonly used web service is the Grid Map.  This gives national or vice county distribution maps of a single taxon (usually a species).  It offers lots of scope for customisation of the map image including record colour and size, date colouring and filtering, backgrounds, vice county and region zooming and dataset filtering (figure 1).  It is often used together with the Species List web service to provide a selectable list to change the species mapped.

     

 

 

 

 

 

 

 

 

 

Figure 1  Examples of maps produced using the Grid Map web service: showing regional, vice county and date range maps (latter courtesy of Harlequin Ladybird Survey)

Figure 2 Grid map on BWARS’s website using BRC’s implementation of the Grid map web service

The potential of this web service was quickly spotted by the Biological Records Centre (BRC), and they produced what must be the easiest to use tool there is to allow you to embed a grid map into your website.  If you know how to build the simplest web page then take a look at these instructions – you only need one line of html code.

A good example of this web service in action is the Bees, Wasps and Ants Recording Society’s website as shown above in figure 2.  They have used the BRC tool together with a species list to embed national distribution maps into their pages.  For them it was important to show only records on the map from their dataset on the Gateway, which is referenced beneath the map.  The species name displayed above the map is also returned by the Grid Map web service.  We also explained the Highland Biological Recording Group's use of Easy Maps in the July eNews.

If you are more interested in getting hold of raw data for a single taxon then you should review the One Species Data  and One Species Location Data web services.  Respectively these return all the raw records and all the unique locations at a specific resolution (eg 1km) for a single taxon.

 

Figure 3 Scottish Natural Heritage's interactive map with records from NBN web services

Data discovery for an area-of-interest

The grid map is good if you know what organism to map, however it is often important to discover what is in your area-of-interest.  Our web services support this type of query by allowing you to specify an area and to request what sort of data you are interested in.  Since the amount of data returned could be huge, the web services allow you to take a hierarchical (‘drill down’) approach from species groups to a species list and eventually to individual observations.

This hierarchy is well illustrated in figure 3, which shows a rich client built by Scottish Natural Heritage to allow data exploration.  As you zoom in on their map, scale dependent functionality becomes available that calls the NBN web services to show the species groups, species lists and records available in the area displayed.  Behind the scenes, the client is sending a bounding box to the appropriate web service, which ‘cookie cuts’ the data from the Gateway’s spatial database.

A very important feature of these web services is how the area-of-interest is defined.  There are 3 main ways (you can see a full specification here):
• supply the key of a site already known to the NBN Gateway, which is supported by the Known Site List web service
• supply a 10km square grid reference
• supply a polygon, bounding box or point-buffer
The polygon option opens up exciting possibilities for the creation of clients that support polygon drawing to find out what organisms occur in and around it.  This is important for conservation and planning.  Figure 4 shows an example provided by the NBN that gives polygon drawing over Bing Maps to explore species records.  Other organisations are developing client tools to assist the screening of planning applications and for agri-environment assessment.

Figure 4  Exploring species records using a polygon

Support web services

In addition to the national and site based web services, which return data and maps on the occurrence of organisms in the UK, there are a number of support web services.  They provide the ancillary information needed when building applications from the main web services, such as:

• Metadata (title, abstract, etc) for a list of Gateway datasets
• Taxon group name from a key
• Taxon synonymy and lower taxa search service
• Look up the name of a site known to the Gateway
• List of sites known to the Gateway
• List of species designations to help filter your requests
• List of habitat layers you can query
• Query habitat layers with a polygon

Key points

The NBN Gateway web services are freely available for anyone to use.  There are however a few important points you need to know when working with them:
• The terms and conditions must be followed: in brief you must reference data providers and acknowledge the NBN Gateway
• The policies governing access to different datasets on the NBN Gateway website apply equally to the web services.  To use raw data you will need ‘download access’, although many data providers do make their data publicly downloadable
• You can provide credentials (ie an NBN Gateway login) to the web services using Digest Authentication which will give you access to data at the higher level granted by dataset providers
• There is an upper limit of 900km2 to the size of the polygon that can be submitted to the web services
• Web services that return large quantities of data will always be relatively slow, so ensure appropriate filters are included to limit the data to just what you need
• Be sure that you use the latest release of the web services

Getting started

Our library of technical information, resources and more can be found here.  If you have specific questions you may find our active forum to be of use.  How you use the web services depends on what you want to do and what technology/programming language you are using.  Here are some starting points:
• C# and Java:  we have pre-built libraries for use directly in your programming projects.  They give you a full object model for interacting with the web services.  The C# dll and Java jar files are available here.
• PHP : MarLIN have provided examples with source code available here, also there is a growing knowledge base of snippets and discussion on the web services forum (see above).
• Other technologies: the most useful information to you is likely to be the wsdl and schema files available here, together with our technical library (see above).

Article written and advice provided by Jon Cooper

If you would like more information you can email Jon