1. OBIS Web Services Mike Flavell OBIS Data Manager ODIN Africa Training Course on Marine Biodiversity Management, Oostende, Belgium, 17 March 2014

2. What are Web Services? A Web service is a method of communication between two electronic devices over the world wide web Delivery of data via the internet. OBIS web services can be accessed manually by people or programatically within software applications We will deal with accessing them manually

3. In What Formats Can I Get OBIS Data? Observations / Gridded Data (XML and CSV) –CSV (comma separated values) –GML (Geography Markup Language v2.0, 3.1, 3.2) XML –Shape File Maps –Image Formats: GIF, JPEG, PNG, SVG, TIFF –KML (plain and compressed) XML for Google Earth browsers OpenLayers (Web Application)

4. GeoServer and OBIS Web Services Open Geospatial Consortium (OGC) Web Services http://www.iobis.org/geoserver Accessed via URLs (HTTP Requests) with different parameters and values

5. Geoserver Layer Preview

6. Layers OBIS Data Layers Other Information Layers Base Map Layers

7. OBIS Base Map Layers LAYER NAMELAYER DESCRIPTION OBIS:GEBCO_relief General Bathymetric Chart of the Oceans (with slight colour Adjustment) OBIS:GEBCOGeneral Bathymetric Chart of the Oceans OBIS:countryWorld Countries

8. OBIS Data Layers LAYER NAMELAYER DESCRIPTION OBIS:drs_with_woa Individual Observations (points)(Condensed Data) linked with World Ocean Atlas Variables OBIS:points_exIndividual Observations (points) (Expanded Data) OBIS:dist_spGridded Species Distributions OBIS:summaries Gridded Biodiversity (Simpson, Shannon, ES50) Number of Observations Number of Taxa per C-square Cell (Varying Resolutions)

9. OBIS Other Information Layers LAYER NAMELAYER DESCRIPTION OBIS:mwhsUNESCO Marine World Heritage Sites OBIS:ihoInternational Hydrographic Organisation Sea Areas OBIS:lmeLarge Marine Ecosystems of the World OBIS:eezsExclusive Economic Zones (OBIS Edit) OBIS:meowMarine Ecoregions of the World, MEOW (Spalding et al., 2007) OBIS:Longhurst_v4_ColorLonghurst Biogeographical Provinces (Colour Coded) OBIS:Longhurst_world_v4_2010Longhurst Biogeographical Provinces (2010 Version, Not Colour Coded) OBIS:WMBWorld Maritime Boundaries (v5 2009-10-01)

10. URL’s and Query Strings OBIS Web services are accessed via URLs (HTTP Requests) For instance to get a jpeg image showing a map of the countries of the world you can use a URL like… http://www.iobis.org/geoserver/OBIS/wms?service=WMS&version=1.1.0&requ est=GetMap&layers=OBIS:country &styles=country&bbox=-180.0,-90.0,180.0,90.0&width=660&height=330 &srs=EPSG:4326&format=image/jpeg

11. URL’s and Query Strings URLs contain different “querystring” parameters & values depending on what you want http://www.iobis.org/geoserver/OBIS/wms?service=WMS&version=1.1.0&requ est=GetMap&layers=OBIS:country &styles=country&bbox=-180.0,-90.0,180.0,90.0&width=660&height=330 &srs=EPSG:4326&format=image/jpeg ? = start of query string & = separator between parameters parameters: name=value service = WMS version = 1.1.0 request = GetMap layers = OBIS:country styles = country bbox = -180.0,-90.0,180.0,90.0 width = 660 height = 330 srs = EPSG:4326 format = image/jpeg

12. GEOSERVER OGC WEB SERVICES

13. WMS – Web Map Service (Map Images) WMS is a protocol to obtain geo-referenced map images over the Internet, that are generated by a map server, using data from a GIS database. Web Map Services GetCapabilities (information on what data is available) GetMap (get map images/kml) GetLegendGraphic (get map data legends) GetFeatureInfo (get more information about a feature on a map)

14. WMS - GetCapabilities Returns an XML document that contains a description (MetaData) of the Web Map Service, such as… – Map image format – WMS version compatibility – Supported Map Projections – Available layers Map bounding box Coordinate reference system URI of the data Whether the layer is mostly opaque or not http://www.iobis.org/geoserver/wms?request=getCapabilities You often need to supply this URL to third party software if you wish to use the OBIS web services in that software

15. WMS – Get Map Returns a map image. Parameters include: width and height of the map, coordinate reference system, layers required, rendering style, image format and size Most Simple URLs – use WMS Reflector (intelligent guess parameters that are not present). http://www.iobis.org/geoserver/OBIS/wms/reflect?format=image/jpeg&layers=OBIS:cou ntry&width=600 More Complicated URLs http://www.iobis.org/geoserver/OBIS/wms?service=WMS&version=1.1.0&request=Get Map&layers=OBIS:country&styles=country&bbox=-180.0,- 90.0,180.0,90.0&width=660&height=330&srs=EPSG:4326&format=image/jpeg http://www.iobis.org/geoserver/OBIS/wms?service=WMS&version=1.1.0&request=Get Map&layers=OBIS:country&styles=polygon&bbox=-20,- 40.0,60.0,40.0&width=640&height=640&srs=EPSG:4326&format=image/jpeg

16. WMS GetLegendGraphic Returns an image of the map's legend image, giving a visual guide to map elements http://www.iobis.org/geoserver/OBIS/wms?request=GetLegendGraphic&l ayer=OBIS:summaries &style=summaries_n_rainbow&width=20&height=20&format=image/png Layer and Style parameters are very important!!!

17. WMS GetFeatureInfo If a layer is marked as 'queryable' then you can request data about any point/polygon (i.e. Feature) displayed on the map image. http://www.iobis.org/geoserver/OBIS/wms?REQUEST=GetFeatureInfo&BBOX=-31.5625,- 51.5625,71.5625,51.5625&SERVICE=WMS&VERSION=1.1.1&X=117&Y=330&INFO_FORMAT =text/html&QUERY_LAYERS=OBIS:GEBCO_relief,OBIS:dist_sp,OBIS:country&FEATURE_CO UNT=50&Layers=OBIS:GEBCO_relief,OBIS:dist_sp,OBIS:country&Styles=&WIDTH=660&HEIG HT=660&format=image/png&srs=EPSG:4326 The server must create the image first! X and Y refer to the pixels of the image!

18. WFS – Web Feature Service Returns data in the specified output format http://www.iobis.org/geoserver/OBIS/ows?service=WFS&version=1.0.0&request=GetFeature&typeName =OBIS:dist_sp &outputFormat=csv &VIEWPARAMS=where:scientific='Calanus finmarchicus';table:dist_sp_5deg;count_column:nincl &MAXFEATURES=20 Understanding the specifics of the OBIS implementation / Database is essential !!!

19. Be aware of URL encoding %3D= %3A: %3B; %20space %26& %2C, %2F/ See http://www.w3schools.com/tags/ref_urlencode.asp for morehttp://www.w3schools.com/tags/ref_urlencode.asp From http://www.iobis.org/geoserver/wms?LAYERS=OBIS%3Adist_sp%2COBIS%3Acountry &STYLES=&FORMAT=image%2Fpng &VIEWPARAMS=where%3Ascientific%3D%27Calanus%20finmarchicus%27%3Btable%3Adist_sp_5deg%3Bcount_column%3Anincl &TILED=false&SERVICE=WMS&VERSION=1.1.1&REQUEST=GetMap&SRS=EPSG%3A4326 &BBOX=-180,-90,180,90&WIDTH=640&HEIGHT=480 To http://www.iobis.org/geoserver/wms?LAYERS=OBIS:dist_sp,OBIS:country &STYLES=&FORMAT=image/png &VIEWPARAMS=where:scientific='Calanus finmarchicus';table:dist_sp_5deg;count_column:nincl &TILED=false&SERVICE=WMS&VERSION=1.1.1&REQUEST=GetMap&SRS=EPSG:4326 &BBOX=-180,-90,180,90&WIDTH=640&HEIGHT=480 Handy URL Decoder/Encoder Tool http://meyerweb.com/eric/tools/dencoder/

20. Standard GeoServer Parameters BBOX: Defines the geographical Bounding Box as 2 x,y (longitude, latitude) coordinate pairs (bottom left and top right) EPSG: Coordinate Projection System – for the web is usually EPSG 4326, but others can be used, especially for polar projections. Geoserver can re-project data from the original projection of a layer to others (See WMS GetCapabilities for supported projections). STYLE: The style set up in Geoserver to apply to the layer, uses pre-configured default styling when not specified. NOTE: It is important to consult the guidance notes to apply the correct styling to layers.

21. BBOX (Bounding Box) 0180-180 WestEast 0 90 -90 South North -30,-30 40,45

22. Map Projections

23. Image Heights and Widths (Aspect Ratio) 1.33 : 1

24. OBIS IMPLEMENTATION SPECIFCS

25. Species Distribution (Gridded) - Maps EXAMPLE Web Map Service URL: http://www.iobis.org/geoserver/wms?LAYERS=OBIS:dist_sp,OBIS:country&STYLES=&FORMAT=im age/png &VIEWPARAMS=where:scientific='Calanus finmarchicus';table:dist_sp_5deg;count_column:nincl &SERVICE=WMS&VERSION=1.1.1&REQUEST=GetMap&SRS=EPSG:4326 &BBOX=-180,-90,180,90&WIDTH=480&HEIGHT=320 Calanus finmarchicus 5 x 5 degree grid

26. Species Distribution (Gridded) - Maps EXAMPLE Web Map Service URL: http://www.iobis.org/geoserver/wms?LAYERS=OBIS:dist_sp,OBIS:country&STYLES=&FORMAT=i mage/png &VIEWPARAMS:where:scientific='Calanus finmarchicus';table:dist_sp_5deg; &SERVICE=WMS&VERSION=1.1.1&REQUEST=GetMap&SRS=EPSG:4326 &BBOX=-180,-90,180,90&WIDTH=480&HEIGHT=320 The VIEWPARAMS is very important! where parameter provides OBIS specific functionality: –scientific = valid (current) name of the Species – check WoRMS –table = required resolution of grid polygons (possible values are:- dist_sp_5deg, dist_sp_1deg, dist_sp_05deg, dist_sp_01deg) Note: more than 1 layer is specified in the URL here (species distribution and country) the order of these is important. Note: If we do not add a parameter for style the default style (configured in GeoGerver) is used.

27. Species Distribution (Gridded) – Map Legends EXAMPLE Web Map Service GetMap URL: http://www.iobis.org/geoserver/wms?LAYERS=OBIS:dist_sp,OBIS:country&STYLES=grid_rainbow&FORMA T=image/png &VIEWPARAMS=where:scientific='Calanus finmarchicus';table:dist_sp_5deg; &TILED=false&SERVICE=WMS&VERSION=1.1.1&REQUEST=GetMap&SRS=EPSG4326 &BBOX=-180,-90,180,90&WIDTH=480&HEIGHT=320 EXAMPLE Web Map Service GetLegendGraphic URL: http://www.iobis.org/geoserver/OBIS/wms?request=GetLegendGraphic&layer=OBIS:dist_sp&style=grid_rain bow&width=20&height=20&format=image/png Calanus finmarchicus 5 x 5 degree grid

28. Species Distribution (Gridded) - Data Example WMS Get Feature Request http://www.iobis.org/geoserver/wms?REQUEST=GetFeatureInfo &BBOX=-168.75,- 112.5,168.75,112.5&SERVICE=WMS&VERSION=1.1.1&X=366&Y=193&INFO_FORMAT=text/html&QUERY_LAYER S=OBIS:dist_sp,OBIS:country&FEATURE_COUNT=50&Viewparams=where:scientific='Calanus finmarchicus';table:dist_sp_5deg;&Layers=OBIS:dist_sp,OBIS:country&Styles=&WIDTH=480&HEIGHT=320&format=im age/png&srs=EPSG:4326 Useful when building applications but not so easy to do this manually But you can use an Open Layers Application and click on a map and see the data for any features. X=X coordinate in pixels of feature measured from upper left corner of the map. Y=Y coordinate in pixels of feature measured from upper left corner of the map. INFO_FORMAT= Return format of feature information, other options include text/xml and text/plain.

29. Species Distribution (Gridded) - Data Example WFS Data Request http://www.iobis.org/geoserver/OBIS/ows?service=WFS&version=1.0.0&request=GetFeature &typeName=OBIS:dist_sp&outputFormat=csv &VIEWPARAMS=where:scientific='Calanus finmarchicus';table:dist_sp_5deg;&MAXFEATURES=20 For a shapefile we can change the outputFormat=shape-zip For all Geoserver WFS output formats see http://docs.geoserver.org/2.3.3/user/services/wfs/outputformats.html (JSON / JSONP / EXCEL are not enabled in OBIS)

30. Observation Data - Maps Map shows Point by Point - the positions where observations have been made http://www.iobis.org/geoserver/wms?LAYERS=OBIS:GEBCO,OBIS:country,OBIS:drs_with_wo a&SERVICE=WMS&VERSION=1.1.1&REQUEST=GetMap&STYLES=&FORMAT=image/png& SRS=EPSG:4326&VIEWPARAMS=where:tname='Carcharodon carcharias'; &BBOX=-180,- 90,180,90&WIDTH=480&HEIGHT=256 Global Map of Point Observations Great White Shark Carcharodon carcharias

31. Observation Data - Points Download the OBIS occurrence data using the Web Feature Service (WFS) to get OBIS observation data… Use layers OBIS:drs_with_woa or OBIS:points_ex For a specific taxon you can specify the taxon name in either of these layers using the VIEWPARAMS=where:tname='Taxonomic name' Note that the OBIS:points_ex layer also supports specifying taxa using a WoRMS aphia_id e.g VIEWPARAMS=where:valid_aphia_id=105838

32. Observation Data - Points Example: to retrieve all records from OBIS as a CSV file for the species Kogia breviceps (pygmy sperm whale) WoRMS Aphia ID = 137113 You would construct a URL as either of the following:- http://www.iobis.org/geoserver/OBIS/ows?service=WFS&version=1.0.0&request=GetFeature&typeNa me=OBIS:points_ex &outputFormat=csv&VIEWPARAMS=where:valid_aphia_id=137113 http://www.iobis.org/geoserver/OBIS/ows?service=WFS&version=1.0.0&request=GetFeature&typeNa me=OBIS:points_ex &outputFormat=csv&VIEWPARAMS=where:tname='Kogia breviceps' The value that you place in the VIEWPARAMS=where: parameter in the query string is your key to constructing a filter on the layer You can use any of the available fields in the layers dataset (note the more complex the filter the longer it may take to execute). THE where: value i.e. where:tname='Kogia breviceps' is actually a postgresql query where clause.

33. Biodiversity Summary - Maps Use layer OBIS:summaries e.g. http://www.iobis.org/geoserver/wms?service=WMS&version=1.1.1&request=GetMap &LAYERS=OBIS:summaries,OBIS:country&styles=summaries_n_rainbow,country &VIEWPARAMS=table:map05deg_with_geom&bbox=-20,-40,60,40 &width=660&height=660&srs=EPSG:4326&Format=image/png Parameters to play with are Styles and VIEWPARAMS (table) ParameterResolution Number of Records styles=summaries_n_rainbow5 x 5 degreetable:map5deg_with_geom Number of Species styles=summaries_s_rainbow1 x 1 degreetable:map1deg_with_geom Shannon Diversity styles=summaries_shannon_rainbow0.5 x 0.5 degreetable:map05deg_with_geom Simpson Diversity styles=summaries_simpson_rainbow0.1 x 0.1 degreetable:map01deg_with_geom ES50Styles=summaries_es50_rainbow

34. Biodiversity Summary - Maps Number of Species Recorded around Africa at 0.5 Degree Resolution: http://www.iobis.org/geoserver/wms?service=WMS&version=1.1.1&request=GetMap &LAYERS=OBIS:summaries,OBIS:country&styles=summaries_n_rainbow,country &VIEWPARAMS=table:map05deg_with_geom&bbox=-20,-40,60,40 &width=660&height=660&srs=EPSG:4326&Format=image/png Note as you need to specify the style for summaries layer, if you wish to include more layers, you must specify the styles for them in the same order as the LAYERS are specified Simpson Biodiversity in Mozambique EEZ at 1 Degree Resolution: http://www.iobis.org/geoserver/wms?service=WMS&version=1.1.1&request=GetMap &LAYERS=OBIS:summaries,OBIS:country,OBIS:eezs &styles=summaries_simpson_rainbow,country,eez_color &VIEWPARAMS=table:map1deg_with_geom&bbox=30,-30,45,-9 &width=660&height=660&srs=EPSG:4326&Format=image/jpeg

35. Biodiversity Summary - Data Use the Web Feature Service (WFS) All columns within the underlying data table / view are returned (so no need to worry about the style parameter) Biodiversity Summary data around Africa at 0.5 Degree Resolution as a shapefile: http://www.iobis.org/geoserver/OBIS/ows?service=WFS&version=1.0.0&request=GetFeature&ty peName=OBIS:summaries&VIEWPARAMS=table:map05deg_with_geom&bbox=-20,- 40,60,40 &srs=EPSG:4326&outputFormat=SHAPE-ZIP Biodiversity in area around Mozambique at 0.1 Degree Resolution as a CSV file: http://www.iobis.org/geoserver/OBIS/ows?service=WFS&version=1.0.0&request=GetFeature&ty peName=OBIS:summaries&VIEWPARAMS=table%3Amap1deg_with_geom&bbox=30,- 30,45,-9 &srs=EPSG:4326&outputFormat=csv

36. Appendix

37. C-squares Gridded data available from OBIS uses the c-squares global grid notation. When obtaining gridded Data you will see a column named “cscode” See http://www.slideshare.net/tony1212/tony-rees-the-csquares- nested-global-grid for more informationhttp://www.slideshare.net/tony1212/tony-rees-the-csquares- nested-global-grid

38. C-squares

39. C-squares aims to provide a hierarchical, globally applicable system of geocodes representing discrete areas on the ground at a range of scales useful for –Spatial indexing and data aggregation –Representation of complex areas (e.g. strings of relevant c-squares) –Simple/rapid web mapping For more information on the c-squares notation see http://www.slideshare.net/tony1212/tony-rees-the- csquares-nested-global-grid

40. Further Information Sources Geoserver Manual > Section on WFS –http://docs.geoserver.org/2.3.0/user/services/wfs/index.htmlhttp://docs.geoserver.org/2.3.0/user/services/wfs/index.html Geoserver Manual > Section on WMS –http://docs.geoserver.org/2.3.0/user/services/wms/index.htmlhttp://docs.geoserver.org/2.3.0/user/services/wms/index.html Geoserver Manual > WMS Reflector –http://docs.geoserver.org/2.3.0/user/tutorials/wmsreflector.htmlhttp://docs.geoserver.org/2.3.0/user/tutorials/wmsreflector.html

42. Finding the OBIS valid_id for a taxon Use the iOBIS Web Portal to get the “OBIS Taxon ID” From the top menu of the web portal select either: Maps > Distribution by Taxon or Search Data > “Click to search & browse taxa”