# Using the OBIS OGC services

OBIS uses GeoServer to expose a number of tables or views as WMS (for raster data) or WFS (for vector data) services. These services can be used by third party applications such as desktop GIS applications or online maps to fetch OBIS data.

## Layers

To view all available layers in GeoServer, click Layer Preview in the left sidebar. Keep in mind that the number of features displayed in the previews is limited.

### SQL views

Some of these layers are SQL views. SQL views don’t just expose a database table, but execute a parameterized query. For example, the OBIS:points_ex layer is a SQL view defined as follows:

SELECT
*
FROM
portal.points_ex
WHERE
%where%


This means that the OBIS:points_ex layer has a parameter where which we will use in the service URL to filter data.

## Constructing service URLs

### WFS requests

For constructing WFS requests, we can start from this URL:

http://www.iobis.org/geoserver/OBIS/ows?service=WFS&version=1.0.0&request=GetFeature


We then need to add a few more parameters:

• typeName: this is the layer we want to access, for example OBIS:points_ex
• outputFormat (optional): this is the file format we want to receive, default is GML3, other supported formats are csv, json and shape-zip (Shapefile)
• maxFeatures (optional): this is the number of features we want to return
• viewparams (optional, only for SQL views): these are the parameters we want to pass to the SQL view

#### Retrieving point data

To retrieve point data using the WFS service, we will use the OBIS:points_ex layer. This layer uses the portal.points_ex database table, and has a parameter where to specify filters. Fields that can be used to filter on include:

• resource_id
• yearcollected
• monthcollected
• daycollected
• valid_id
• valid_aphia_id
• tname
• storedpath
• eez_id

To get an overview of all fields, execute this WFS request.

To retrieve all occurrences of Abra alba, we can do:

http://www.iobis.org/geoserver/OBIS/ows?service=WFS&version=1.0.0&request=GetFeature&typeName=OBIS:points_ex&outputformat=csv&viewparams=where:tname=%27Abra%20alba%27


To get all occurrences of the genus Abra, we could try this:

http://www.iobis.org/geoserver/OBIS/ows?service=WFS&version=1.0.0&request=GetFeature&typeName=OBIS:points_ex&outputformat=csv&viewparams=where:tname=%27Abra%27


but that will only give us the records that were identified at the genus level.

If only valid_id, valid_aphia_id or tname are used as a filter, child taxa will not be included in the result set.

The solution to this problem is to use the storedpath field as well. storedpath is a string containing all parent taxon IDs delimited by x. So in order to get all occurrences of Abra, including all child taxa, we can do:

http://www.iobis.org/geoserver/OBIS/ows?service=WFS&version=1.0.0&request=GetFeature&typeName=OBIS:points_ex&outputformat=csv&viewparams=where%3Avalid_id%3D395447%20or%20storedpath%20like%20%27%25395447%25%27%20%0A


Note that this will be quite slow. We can speed things up if we know the complete storedpath:

http://www.iobis.org/geoserver/OBIS/ows?service=WFS&version=1.0.0&request=GetFeature&typeName=OBIS:points_ex&outputformat=csv&viewparams=where%3Avalid_id%3D395447%20or%20storedpath%20like%20%27x739909x738303x752044x739927x697902x781789x677405x517409x700476x395447%25%27%20


But there’s a pitfall here. These results will not include occurrences reported with a synonym such as Syndesma ovata or Abrina lunella.

### WMS requests

We can use the WMS service to generate maps by extending this URL:

http://www.iobis.org/geoserver/wms?SERVICE=WMS&VERSION=1.1.1&REQUEST=GetMap&STYLES=&FORMAT=image/png&SRS=EPSG:4326


Again, we will need to add some parameters:

• layers: the layers we want to use for our map, comma separated
• bbox: the bounding box of our map, formatted as minlon,minlat,maxlon,maxlat
• width: the image width in pixels
• height: the image height in pixels
• styles: which styling to use, optional if you want to use the default style defined for the layer, use comma separated styles in case there are multiple layers
• viewparams: for filtering data and selecting the database table to use or the column to visualize

#### Visualizing point data

For making maps, we can use the OBIS:drs_with_woa layer, which will be faster than OBIS:points_ex.

For example, to display all Pterois volitans (OBIS ID 501083) occurrences on top of the GEBCO and country base maps, we can do:

http://www.iobis.org/geoserver/wms?SERVICE=WMS&VERSION=1.1.1&REQUEST=GetMap&FORMAT=image/png&SRS=EPSG:4326&LAYERS=OBIS:GEBCO,OBIS:country,OBIS:drs_with_woa&VIEWPARAMS=where:valid_id=501083&BBOX=-180,-90,180,90&WIDTH=480&HEIGHT=256


#### Visualizing gridded data

##### Species distributions

For plotting species distributions, we can to use the OBIS:dist_sp layer which has the following viewparams:

• where: filter on valid_id or scientific
• table: one of dist_sp_5deg, dist_sp_1deg, dist_sp_05deg, dist_sp_01deg
• count_column: nincl (child taxa included) or nexcl (child taxa excluded, default)

For example:

http://www.iobis.org/geoserver/wms?SERVICE=WMS&VERSION=1.1.1&REQUEST=GetMap&FORMAT=image/png&SRS=EPSG:4326&LAYERS=OBIS:dist_sp,OBIS:country&VIEWPARAMS=where:valid_id=501083;count_column:nincl;table:dist_sp_5deg&BBOX=-180,-90,180,90&WIDTH=480&HEIGHT=256


##### Summaries

Summaries are available from the OBIS:summaries layer. This layer takes the following viewparams:

• table: one of map5deg_with_geom, map1deg_with_geom, map05deg_with_geom, map01deg_with_geom

To select the biodiversity summary to be displayed, use the styles parameter:

• number of records: styles=summaries_n_rainbow
• number of species: styles=summaries_s_rainbow
• Shannon diversity: styles=summaries_shannon_rainbow
• Simpson diversity: styles=summaries_simpson_rainbow
• ES50: styles=summaries_es50_rainbow

To display the number of records on a 5 degrees grid:

http://www.iobis.org/geoserver/wms?SERVICE=WMS&VERSION=1.1.1&REQUEST=GetMap&FORMAT=image/png&SRS=EPSG:4326&LAYERS=OBIS:summaries,OBIS:country&styles=summaries_n_rainbow,country&VIEWPARAMS=table:map5deg_with_geom&BBOX=-180,-90,180,90&WIDTH=480&HEIGHT=256


Note that we need to specify a style for the OBIS:country layer as well, not doing so will result in an error.

##### Map legends

Use the WMS GetLegendGraphic request to get a legend image for your map. For example, for the map above:

http://www.iobis.org/geoserver/wms?SERVICE=WMS&VERSION=1.1.1&REQUEST=GetLegendGraphic&FORMAT=image/png&layer=OBIS:summaries&styles=summaries_n_rainbow