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