Atlas API - Developer Notes
Specifying fields returned in an occurrence search
Occurrence Search returns all fields. For example
https://records-ws.nbnatlas.org/occurrences/search?q=*:*&fq=genus:Vulpes
````
returns
"occurrences": [ { "uuid": "f027439c-9877-4ae9-99c0-f1a08f797dbc", "occurrenceID": "88715", "taxonConceptID": "NHMSYS0000080188", "eventDate": 1494806400000, "occurrenceYear": 1483228800000, "scientificName": "Vulpes vulpes", "vernacularName": "Red Fox", "taxonRank": "species", "taxonRankID": 7000, "country": "United Kingdom" } ]
BUT messing it around revealed you can actually specify which fields you want returning by adding a fl parameter - well sometimes you can and you have to use camel case
This returns empty records:
https://records-ws.nbnatlas.org/occurrences/search?q=:&fq=genus:Vulpes&fl=occurrenceID
but try camel case instead and it works
https://records-ws.nbnatlas.org/occurrences/search?q=:&fq=genus:Vulpes&fl=occurrence_id
but not all camel case works, eg vernacular_name doesn't:
https://records-ws.nbnatlas.org/occurrences/search?q=:&fq=genus:Vulpes&fl=country,occurrence_id,vernacular_name
Turns out, you get the field name by going to [https://records-ws.nbnatlas.org/index/fields]. For vernacularName that gives:
{ "name": "common_name", "dataType": "string", "indexed": true, "stored": true, "multivalue": false, "docvalue": true, "description": "Common name (processed)", "info": "http://rs.tdwg.org/dwc/terms/vernacularName", "jsonName": "vernacularName", "dwcTerm": "vernacularName", "classs": "Taxon" }
Note: you are interested in mapping "jsonName" to "name".
So use common_name in the fl parameter:
https://records-ws.nbnatlas.org/occurrences/search?q=:&fq=genus:Vulpes&fl=country,occurrence_id,common_name ```
Improvements
Add fl field to api document and explain the look up page for finding the fl field name values
Occurrence cube
Dimensions: Decade × Species Group × SSSI
Groups taken from https://records-ws.nbnatlas.org/explore/groups
SSSI: https://records-ws.nbnatlas.org/occurrence/facets?q=:&facets=cl280
Hence cube slice :"Insects" https://records-ws.nbnatlas.org/occurrence/facets?q=(occurrence_decade_i:2000 AND species_group:"Insects" AND ( cl280:"North Norfolk Coast" OR cl280:"Dungeness, Romney Marsh and Rye Bay" OR cl280:"Sandwich Bay to Hacklinge Marshes" OR cl280:"Humber Estuary" OR cl280:"Dee Estuary" OR cl280:"The New Forest" OR cl280:"Breckland Forest" OR cl280:"The Wash" OR cl280:"Morecambe Bay" OR cl280:"Minsmere-Walberswick Heaths and Marshes" ))&facets=cl280
WMS
WMS returns image tiles. This means clicking on the points shows no information on that record. This is how WMS works.
The WMS getFeatureInfo, which is suppose to return info on a features, does not work (although I may not have been using it correctly!).
https://records-ws.nbnatlas.org/ogc/getFeatureInfo?q=cl188%3A%22Cofnod%20-%20North%20Wales%20Environmental%20Information%20Service%22&fq=occurrence_status%3Apresent&fq=(taxon_name%3A%22Cyanistes%20maenas%22%20OR%20taxon_name%3A%22Prunella%20modularis%22)&service=WMS&lat=52.9409703639322&lon=-4.53460693359375
However, the Leaflet maps on the atlas, when you click on a point, make a call like the following, passing in the lat/lon:
https://records-ws.nbnatlas.org/occurrences/info?q=taxon_name%3A%22Carcinus%20maenas%22%20AND%20cl188%3A%22Cofnod%20-%20North%20Wales%20Environmental%20Information%20Service%22&fq=occurrence_status%3Apresent&callback=jQuery34103109978362349104_1764534776229&zoom=9&lat=52.9409703639322&lon=-4.53460693359375&radius=1.5&format=json&_=1764534776237
and that returns the record/s id, so another call is then made to get record and the popup content is generated from those fields. So thats not standard and not something Leaflet can make use of obviously.
The Atlas OGC service only supports WMS which just returns an image. This means the points arent features so clicking on an occurrence point doesnt do anything. Instead, you have to implement a map click event handler to:
- Get lat/lon from Leaflet
- send lat/lon to /occurrences/info
- if occurrence records found at the lat/lon for the query, get occurrence details
The JS behind the map on records.nbnatlas.org shows how this is done.