Web service API

The webservices are listed by category. To list by application, click here.

Species profile - Taxonomic name, concept lookups services

Webservices change log

• Edit Example Copy

  Get higher classifications for GUID - https://species-ws.nbnatlas.org/classification/{guid}   https://species-ws.nbnatlas.org/classification/{guid}

  GET JSON

  • GET
  • JSON

  Provides a list of higher taxa for the requested taxon.

  Examples

  • Edit

    List higher classifications for GUID

    Higher taxa for Homo Sapiens

    URL: https://species-ws.nbnatlas.org/classification/NHMSYS0000376773
    

• Edit Example Copy

  Species search - https://species-ws.nbnatlas.org/search?q={q}&fq={fq}   https://species-ws.nbnatlas.org/search?q={q}&fq={fq}

  GET JSON

  • GET
  • JSON

  Species text search services.

  q	String	Query of the form field:value e.g. q=rk_genus:Macropus or a free text search e.g. q=Macropus
  fq	String	Filters to be applied to the original query. These are additional params of the form fq=INDEXEDFIELD:VALUE e.g. fq=rank:kingdom. See https://species-ws.nbnatlas.org/indexFields for all the fields that are queryable.
  start	Integer	Record offset, to enable paging
  pageSize	Integer	Number of records to return
  sort	String	Field to sort on
  dir	String	Sort direction "asc" or "desc"
  facets	String	comma separated list of fields to display facets for. Available fields listed https://species-ws.nbnatlas.org/indexFields.

  Examples

  • Edit

    Search for facets

    Find the different phylum in the animalia kingdom and count records in each.

    URL: https://species-ws.nbnatlas.org/search?q=&fq=rk_kingdom:Animalia&facets=rk_phylum&pageSize=0
    

  • Edit

    Taxonomy Explorer

    Many of the queries use SOLR search terms. For a primer on this topic, with specific with regard to the NBN Atlas, please see: Query Primer

    URL: https://species-ws.nbnatlas.org/search
    Online demo: https://duncanrowland.github.io/taxa/
    

  • Edit

    Species record 'Man'

    Find the species record for commonNameSingle = Man

    URL: https://species-ws.nbnatlas.org/search?q=&fq=commonNameSingle:Man
    

• Edit Example Copy

  Bulk lookup by GUID - https://species-ws.nbnatlas.org/species/guids/bulklookup   https://species-ws.nbnatlas.org/species/guids/bulklookup

  POST JSON

  • POST
  • JSON

  .Requires a JSON post body.

  ["NHMSYS0000376773"] or ["NHMSYS0000376773","NHMSYS0000080188"]

  Example output

  {
      "searchDTOList":[
          {
              "guid":"NHMSYS0000376773",
              "name":"Homo sapiens",
              "scientificName":"Homo sapiens",
              "author":"Linnaeus, 1758",
              "nameComplete":"Homo sapiens Linnaeus, 1758",
              "rank":"species",
              "kingdom":"Animalia",
              "phylum":"Chordata",
              "classs":"Mammalia",
              "order":"Primates",
              "family":"Hominidae",
              "genus":"Homo",
              "datasetName":null,
              "datasetID":null,
              "commonNameSingle":"Man"
          }
      ]
  }

  View : https://species-ws.nbnatlas.org/species/guids/bulklookup

• Edit Example Copy

  Species download - https://species-ws.nbnatlas.org/download?q={q}&fq={fq}   https://species-ws.nbnatlas.org/download?q={q}&fq={fq}

  GET CSV

  • GET
  • CSV

  CSV species record field download

  q *	String	Query of the form field:value e.g. q=genus:Macropus or a free text search e.g. q=Macropus
  fq	String	Filters to be applied to the original query. These are additional params of the form fq=INDEXEDFIELD:VALUE e.g. fq=rk_kingdom:Fungi. See https://species-ws.nbnatlas.org/indexFields for all the fields that a queryable.
  fields	String	A comma separated list of SOLR fields to include in the download. Fields can be included in the download if they have been stored. Default fields: taxonConceptID, rank, scientificName, establishmentMeans, rk_genus, rk_family, rk_order, rk_class, rk_phylum, rk_kingdom, datasetName
  file	String	The name of the file to be downloaded. Default: 'species.csv'

  Examples

  • Edit

    Download data for 'Homo Sapiens'

    Download specific fields for the Homo Sapiens species record

    URL: https://species-ws.nbnatlas.org/download?q=&fq=scientificName:*sapiens&fields=guid,scientificName
    

• Edit Example Copy

  Species lookup with GUID - https://species-ws.nbnatlas.org/species/{guid}   https://species-ws.nbnatlas.org/species/{guid}

  GET JSON JSONP

  • GET
  • JSON
  • JSONP

  Species lookup with GUID

  guid *	String	The guid for the taxon concept
  callback	String	JSONP callback

  Examples

  • Edit

    Red Fox (JSONP)

    Lookup Red Fox with GUID returning JSONP

    URL: https://species-ws.nbnatlas.org/species/NHMSYS0000080188?callback=myJsonpCallback
    

  • Edit

    Red Fox (JSON)

    Lookup Red Fox with GUID returning JSON

    URL: https://species-ws.nbnatlas.org/species/NHMSYS0000080188
    History

• Edit Example Copy

  Bulk species lookup - https://species-ws.nbnatlas.org/species/lookup/bulk   https://species-ws.nbnatlas.org/species/lookup/bulk

  POST JSON

  • POST
  • JSON

  Requires a JSON map as a post body. The JSON map must contain a "names" key that is the list of scientific names.

  {"names":["Man"]} or {"names":["Man","Fox"]}

  Example output

  [
      {
          "identifier":"NHMSYS0000376773",
          "guid":"NHMSYS0000376773",
          "parentGuid":"NHMSYS0000376769",
          "name":"Homo sapiens",
          "nameComplete":"Homo sapiens Linnaeus, 1758",
          "commonName":[
              "Man"
          ],
          "commonNameSingle":"Man",
          "rank":"species",
          "rankId":7000,
          "acceptedConceptGuid":"NHMSYS0000376773",
          "acceptedConceptName":"Homo sapiens",
          "taxonomicStatus":"accepted",
          "imageId":null,
          "imageUrl":"",
          "thumbnailUrl":"",
          "largeImageUrl":"",
          "smallImageUrl":"",
          "imageMetadataUrl":"",
          "kingdom":"Animalia",
          "phylum":"Chordata",
          "classs":"Mammalia",
          "order":"Primates",
          "family":"Hominidae",
          "genus":"Homo",
          "author":"Linnaeus, 1758",
          "linkIdentifier":null
      }
  ]

  View : https://species-ws.nbnatlas.org/species/lookup/bulk

• Edit Example Copy

  Species indexed fields - https://species-ws.nbnatlas.org/admin/indexFields   https://species-ws.nbnatlas.org/admin/indexFields

  GET JSON

  • GET
  • JSON

  List in JSON the index fields within the species datasets (N.B. Not the same as the records datasets).
  Notes when using these fields in search queries:
  - Only stored values will be returned.
  - Text fields will be fuzzy matched.
  (See Query Primer documentation).
  

  View : https://species-ws.nbnatlas.org/admin/indexFields

• Edit Example Copy

  Bulk species lookup - https://species-ws.nbnatlas.org/guid/batch?q={q}   https://species-ws.nbnatlas.org/guid/batch?q={q}

  GET JSON JSONP

  • GET
  • JSON
  • JSONP

  Lookup one or more "name" queries for matching taxon concepts in the species datasets.
  Multiple names can be specified with repeating q params. E.g. ?q=fox&q=man

  q *	String	Query string
  callback	String	Name of callback function to wrap JSON output in. Provided for JSONP cross-domain requests.

  Examples

  • Edit

    Bulk species lookup

    Queries for taxon concepts matching "Fox"

    URL: https://species-ws.nbnatlas.org/guid/batch?q=Fox
    

Occurrence - Specimen & observation data searching

• Edit Example Copy

  Occurrence details - https://records-ws.nbnatlas.org/occurrence/{uuid}   https://records-ws.nbnatlas.org/occurrence/{uuid}

  GET JSON

  • GET
  • JSON

  Retrieve the full details of a record.

  Examples

  • Edit

    Example record full details

    "Vulpes vulpes" record full details

    URL: https://records-ws.nbnatlas.org/occurrences/00e11378-510a-41e4-beea-d8e4d1d9a001
    

• Edit Example Copy

  Occurrence Facet Download - https://records-ws.nbnatlas.org/occurrences/facets/download?q={q}   https://records-ws.nbnatlas.org/occurrences/facets/download?q={q}

  GET CSV

  • GET
  • CSV

  CSV download of a single facet.
  Tip: range based faceting is supported by using the SOLR parameters.

  The facets, q and fq values support the stored & indexed fields

  facets	String	eg. species_guid
  fq	String	additional filters. eg. fq=state_conservation:Endangered
  q *	String	Query of the form field:value e.g. q=genus:Macropus or a free text search e.g. q=Macropus

  Examples

  • Edit

    Species facet

    Download a list of species recorded on a specific date

    URL: https://records-ws.nbnatlas.org/occurrences/facets/download?q=*:*&fq=occurrence_date:1626-01-01T00:00:00Z&facets=species
    

  • Edit

    Download historic sample dates

    Download a list of dates from the 1600s in which a recording occurred.

    URL: https://records-ws.nbnatlas.org/occurrences/facets/download?q=*:*&fq=occurrence_date:[1600-01-01T00:00:00Z TO 1699-12-31T00:00:00Z]&facets=occurrence_date
    

• Edit Example Copy

  Occurrence search - https://records-ws.nbnatlas.org/occurrences/search?q={q}&fq={fq}   https://records-ws.nbnatlas.org/occurrences/search?q={q}&fq={fq}

  GET JSON

  • GET
  • JSON

  JSON occurrence search. In addition to the parameters listed, range based faceting is supported by using the SOLR parameters.

  The facets, q and fq values support the stored & indexed fields

  q *	String	Query of the form field:value e.g. q=genus:Macropus or a free text search e.g. q=Macropus
  fq	String	Filters to be applied to the original query. These are additional params of the form fq=INDEXEDFIELD:VALUE e.g. fq=kingdom:Fungi. See https://records-ws.nbnatlas.org/index/fields for all the fields that a queryable.
  facet	String	Supported values are "off" or "on". By default, its "on". This is worth switching off if facetting is not required, to reduce the JSON being sent.
  facets	String	Comma separated list of the fields to create facets on e.g. facets=basis_of_record.
  pageSize	Integer	Number of records to return (default=10)
  startIndex	Integer	Record offset, to enable paging
  sort	String	The indexed field to sort by
  dir	String	Supports "asc" or "desc"
  flimit	Integer	Maximum number of facet values to return (default=30)
  fsort	String	Method in which to sort the facets either "count" or "index"
  foffset	Integer	Facet offset, to enable paging
  fprefix	String	Limits facets to values that start with the supplied value
  lat	Double	The decimal latitude to limit records to. Use with lon and radius to specify a "search" circle
  lon	Double	The decimal latitude to limit records to. Use with lon and radius to specify a "search" circle
  radius	Double	The radius in which to limit records (relative to the lat, lon point). Use with lat and lon to specify a "search" circle.
  wkt	String	The polygon area in which to limit records. For information on Well known text see this

  Examples

  • Edit

    Search for the records for the genus Vulpes

    Search for the records for the genus Vulpes returning taxonomic, geospatial, temporal information for occurrences, returning only the first ten.

    URL: https://records-ws.nbnatlas.org/occurrences/search?q=*:*&fq=genus:Vulpes
    

  • Edit

    Peter Neish's Visualisation

    Adapted from ALA example

    URL: https://records-ws.nbnatlas.org/occurrences/search
    Online demo: https://duncanrowland.github.io/NBNQueryExample/
    

• Edit Example Copy

  Occurrence query cache - https://records-ws.nbnatlas.org/webportal/params   https://records-ws.nbnatlas.org/webportal/params

  POST TEXT

  • POST
  • TEXT

  Add query details to a cache to reduce the size of the query params that are being passed around. This is particularly useful if you requests are too large for a GET.

  wkt	String	The polygon area in which to limit records. For information on Well known text see this
  q *	String	Query of the form field:value e.g. q=genus:Macropus or a free text search e.g. q=Macropus
  fq	String	Filters to be applied to the original query. These are additional params of the form fq=INDEXEDFIELD:VALUE e.g. fq=kingdom:Fungi. See https://records-ws.nbnatlas.org/index/fields for all the fields that a queryable.

  Example output

  POST: https://records-ws.nbnatlas.org/webportal/params?q=*:*&fq=genus:Vulpes
  Will return an integer value 'ID' that can then be used in occurrences searches.
  e.g.
  GET: https://records-ws.nbnatlas.org/occurrences/search?q=qid:'ID'

• Edit Example Copy

  Occurrence download - https://records-ws.nbnatlas.org/occurrences/index/download   https://records-ws.nbnatlas.org/occurrences/index/download

  GET SHP CSV

  • GET
  • SHP
  • CSV

  Occurrence download - limited to first 500,00 records.
  Downloads of the following formats are supported:

  • CSV
  • TSV
  • SHAPE

  The output format is determined based on the fileType param.

  The download will return a ZIP file that contains the data in the requested format and a Readme and citataion.csv.
  Please be aware that a shape file download will be large. Each of the fields is included as a feature. It is advised to select a subset of information to be included.

  q *	String	Query of the form field:value e.g. q=genus:Macropus or a free text search e.g. q=Macropus
  fq	String	Filters to be applied to the original query. These are additional params of the form fq=INDEXEDFIELD:VALUE e.g. fq=kingdom:Fungi. See https://records-ws.nbnatlas.org/index/fields for all the fields that a queryable.
  lat	Double	The decimal latitude to limit records to. Use with lon and radius to specify a "search" circle
  lon	Double	The decimal latitude to limit records to. Use with lon and radius to specify a "search" circle
  radius	Double	The radius in which to limit records (relative to the lat, lon point). Use with lat and lon to specify a "search" circle.
  wkt	String	The polygon area in which to limit records. For information on Well known text
  file	String	The name of the file to produce. This will default to data.
  email	String	The email address of the user performing the download.
  reason	String	A user supplied description of the reason for the download
  fields	String	A CSV list of fields to include in the download. This can be a stored index field name OR a Darwin Core Field name that is also a stored index field. There is a default list (documented in a Google Doc) that is included if no value is supplied. A list of index fields can be found here: https://records-ws.nbnatlas.org/index/fields.
  extra	String	a CSV list of fields in include in addition to the "fields". This is useful if you would like to make use of the default fields and include extra fields.
  reasonTypeId *	Integer	A reason code for the download. See reasons for valid values.
  fileType	String	The file format for the download. One of csv, tsv or shp. When no value is supplied csv is assumed.
  sourceTypeId	Integer	A source type code for the download. This indicates which system requested the download. See sources for valid values.
  qa	String	A CSV list of record issues to include in the download. See assertions for possible values to include. When no value is supplied all the record issues are included. To include NO record issues set this value to "none". To include ALL INCLUDING EMPTY record issue columns set this value to "includeall".
  esc	String	The Escape character to use for a CSV file. This will default to " in order to produce an Excel compliant CSV file.
  sep	String	The separator character to use for a CSV file. This will default to , .
  dwcHeaders	Boolean	Use DwC field names in the download where available. The default value is "false".

  Examples

  • Edit

    Disable Record Issues in download

    A "test" (recordings of genus Vulpes recording from a 10k radius in London) in a download that does not include record assertions.

    URL: https://records-ws.nbnatlas.org/occurrences/index/download?reasonTypeId=10&q=*:*&fq=genus:Vulpes&lat=51.5074&lon=0.1278&radius=10.0&qa=none
    

• Edit Example Copy

  Compare original vs processed - https://records-ws.nbnatlas.org/occurrence/compare/{uuid}   https://records-ws.nbnatlas.org/occurrence/compare/{uuid}

  GET JSON

  • GET
  • JSON

  Compare the original record to the processed (interpreted) version of the record.

  UUID

  String

  The identifier for the record.

  Examples

  • Edit

    Fox record

    Compare original vs processed fox record.

    URL: https://records-ws.nbnatlas.org/occurrence/compare/00e11378-510a-41e4-beea-d8e4d1d9a001
    

• Edit Example Copy

  Occurrence indexed fields - https://records-ws.nbnatlas.org/index/fields   https://records-ws.nbnatlas.org/index/fields

  GET JSON

  • GET
  • JSON

  List in JSON the index fields within the occurrence store.
  Notes when using these fields in search queries:
  - Only stored values will be returned.
  - Text fields will be fuzzy matched.
  (See Query Primer documentation).
  

  View : https://records-ws.nbnatlas.org/index/fields

• Edit Example Copy

  Retrieve all species groups and counts - https://records-ws.nbnatlas.org/explore/groups   https://records-ws.nbnatlas.org/explore/groups

  GET JSON

  • GET
  • JSON

  Given search and optionally a filter, location and radius, it returns: a list of groups and how many records are in each.

  lat	Double	The latitude to limit the query by (must be used with lon and radius)
  lon	Double	The longitude to limit the query by (must be used with lat and radius)
  q	String	The query which defaults to *:* when not supplied
  fq	String	The filter query
  radius	Double	Radius (km) (for use with lat, lon)

  Examples

  • Edit

    Species groups

    Counts for species groups for records of genus:Vulpes?

    URL: https://records-ws.nbnatlas.org/explore/groups?q=*:*&fq=genus:Vulpes
    

• Edit Example Copy

  Retrieve the counts for a specific group - https://records-ws.nbnatlas.org/explore/counts/group/{group}   https://records-ws.nbnatlas.org/explore/counts/group/{group}

  GET JSON

  • GET
  • JSON

  Given a group (e.g. Mammals) and optionally a filter, location and radius, it returns:
  [number of species records in the group, number of species in that group]

  lon	Double	The longitude to limit the query by (must be used with lat and radius)
  fq	String	The filter query
  q	String	The query which defaults to *:* when not supplied
  lat	Double	The latitude to limit the query by (must be used with lon and radius)
  radius	Double	Radius (km) (for use with lat, lon)

  Examples

  • Edit

    Specific species group

    How many of the records returned from the filter genus:Vulpes that are within 10km of the center of London are in the Mammals species group? (and how many different species is that?)

    URL: https://records-ws.nbnatlas.org/explore/counts/group/Mammals?q=*:*&fq=genus:Vulpes&lat=51.5074&lon=0.1278&radius=10.0
    

• Edit Example Copy

  Download a list of species in a group - https://records-ws.nbnatlas.org/explore/group/{group}/download   https://records-ws.nbnatlas.org/explore/group/{group}/download

  GET ZIP CSV

  • GET
  • ZIP
  • CSV

  Download a list of species that contribute to a group (e.g. Birds) and their counts (optionally in a specific area).

  q	String	The query which defaults to *:* when not supplied
  lat	Double	The latitude to limit the query by (must be used with lon and radius)
  lon	Double	The longitude to limit the query by (must be used with lat and radius)
  fq	String	The filter query
  radius	Double	Radius (km) (for use with lat, lon)

  Examples

  • Edit

    Birds in Central London

    Download a list of species and their counts that contribute to the Birds group from a 1km radius in the center of London.

    URL: https://records-ws.nbnatlas.org/explore/group/Birds/download?lat=51.5074&lon=0.1278&radius=1.0
    

• Edit Example Copy

  Retrieve list of species and counts for a group - https://records-ws.nbnatlas.org/explore/group/{group}   https://records-ws.nbnatlas.org/explore/group/{group}

  GET JSON

  • GET
  • JSON

  Retreive a list of species that contribute to a group (e.g. Birds) and their counts (optionally in a specific area).
  Supports the additional parameters pageSize, start, sort, dir - to allow paging through the results, and location.

  q	String	The query which defaults to : when not supplied
  lat	Double	The latitude to limit the query by (must be used with lon and radius)
  fq	String	The filter query
  lon	Double	The longitude to limit the query by (must be used with lat and radius)
  pageSize	Integer	Number of records to return
  start	Integer	Record offset, to enable paging
  sort	String
  dir	String

  Examples

  • Edit

    Birds in Central London (json)

    Retrieve a paged list (default size 10) of species and their counts that contribute to the Birds group from a 1km radius in the center of London.

    URL: https://records-ws.nbnatlas.org/explore/group/Birds?lat=51.5074&lon=0.1278&radius=1.0&start=0
    

• Edit Example Copy

  Retrieve geojson cluster for group - https://records-ws.nbnatlas.org/geojson/radius-points   https://records-ws.nbnatlas.org/geojson/radius-points

  GET GEOJSON

  • GET
  • GEOJSON

  Download geojson, i.e. coordinates points for localise group (e.g. can be viewed http://geojson.io)
  Supports the additional parameters pageSize, start, sort, dir - to allow paging through the results.

  q	String	The query which defaults to : when not supplied
  start	Integer	Record offset, to enable paging
  pageSize	Integer	Number of records to return
  fq	String	The filter query
  sort	String
  dir	String
  lat	Double	The latitude to limit the query by (must be used with lon and radius)
  lon	Double	The longitude to limit the query by (must be used with lat and radius)
  group	String	Species group
  zoom	Integer	Zoom level
  callback	String	JSONP callback

  Examples

  • Edit

    GeoJSON cluster for Grassington

    Returns location of records for map display.

    URL: https://records-ws.nbnatlas.org/geojson/radius-points?lat=54.079&lon=-1.988&radius=5&fq=geospatial_kosher%3Atrue&qc=&zoom=14&group=ALL_SPECIES
    Online demo: http://geojson.io/#map=12/54.0732/-1.9889
    

• Edit Example Copy

  Occurrence Facet Search - https://records-ws.nbnatlas.org/occurrence/facets?q={q}   https://records-ws.nbnatlas.org/occurrence/facets?q={q}

  GET JSON

  • GET
  • JSON

  Use this service to retrieve counts for facets e.g. the number of taxa matching a query.
  N.B. The fq parameter is ignored for this web service. If required, include any filters into the q param with an AND clause.

  foffset	Integer	Facet offset, to enable paging
  radius	Double	The radius in which to limit records (relative to the lat, lon point). Use with lat and lon to specify a "search" circle.
  fsort	String	Method in which to sort the facets either "count" or "index"
  q *	String	Query of the form field:value e.g. q=genus:Macropus or a free text search e.g. q=Macropus
  sort	String	The indexed field to sort by
  startIndex	Integer	Record offset, to enable paging
  lat	Double	The decimal latitude to limit records to. Use with lon and radius to specify a "search" circle
  dir	String	Supports "asc" or "desc"
  lon	Double	The decimal latitude to limit records to. Use with lon and radius to specify a "search" circle
  flimit	Integer	Maximum number of facet values to return
  fprefix	String	Limits facets to values that start with the supplied value
  facets	String	Comma separated list of the fields to create facets on e.g. facets=basis_of_record.
  wkt	String	The polygon area in which to limit records. For information on Well known text see this
  lookup	Boolean	Only suitable for facets that are returning taxon GUIDs (e.g.species_guid) If set to true this will try to perform a taxon lookup against the guid and will return additional taxon information

  Examples

  • Edit

    Top ten data resources

    Return the top ten data resources by number of records

    URL: https://records-ws.nbnatlas.org/occurrence/facets?flimit=10&facets=data_resource_uid
    

  • Edit

    Retrieve historic bird counts

    Retrieve a count of species of Birds in the UK using the "RSPB Big Garden Birdwatch winter sightings in the UK in 2009" (i.e. data_resource_uid:dr477) and return the top 10.

    URL: https://records-ws.nbnatlas.org/occurrence/facets?facets=taxon_name,common_name&q=data_resource_uid:dr477&flimit=10
    

Geospatial - Including intersection services and gazetteer information

• Edit Example Copy

  Layers listing - https://layers.nbnatlas.org/ws/layers   https://layers.nbnatlas.org/ws/layers

  GET JSON

  • GET
  • JSON

  Get a list of all layers

  View : https://layers.nbnatlas.org/ws/layers

• Edit Example Copy

  Gridded layers listing - https://layers.nbnatlas.org/ws/layers/grids   https://layers.nbnatlas.org/ws/layers/grids

  GET JSON

  • GET
  • JSON

  Get a list of all environmental/gridded layers

  View : https://layers.nbnatlas.org/ws/layers/grids

• Edit Example Copy

  Shape layers listing - https://layers.nbnatlas.org/ws/layers/shapes   https://layers.nbnatlas.org/ws/layers/shapes

  GET JSON

  • GET
  • JSON

  Get a list of all contextual layers (e.g. political boundaries)

  View : https://layers.nbnatlas.org/ws/layers/shapes

• Edit Example Copy

  List of geospatial fields - https://layers.nbnatlas.org/ws/fields   https://layers.nbnatlas.org/ws/fields

  GET JSON

  • GET
  • JSON

  Return a list of fields: name, id, description, etc.

  View : https://layers.nbnatlas.org/ws/fields

• Edit Example Copy

  Details of a specific geospatial field - https://layers.nbnatlas.org/ws/field/{fid}   https://layers.nbnatlas.org/ws/field/{fid}

  GET JSON

  • GET
  • JSON

  Return the details on a specific field using its field ID fid the results contains: name, ID, description, bounding box, area, etc.

  Examples

  • Edit

    Fetch Watsonian Vice Counties object

    Fetch the JSON describing Watsonian Vice Counties (field ID "cl14").

    URL: https://layers.nbnatlas.org/ws/field/cl14
    

• Edit Example Copy

  Fetch an array of objects belonging to a specific field - https://layers.nbnatlas.org/ws/objects/{fid}   https://layers.nbnatlas.org/ws/objects/{fid}

  GET JSON

  • GET
  • JSON

  Return an array of objects that are members of the specified field ID fid. This does not return any information for the field, only its children.

  Examples

  • Edit

    Fetch Watsonian Vice Counties

    Fetch an array of objects that are members of the Watsonian Vice Counties.

    URL: https://layers.nbnatlas.org/ws/objects/cl14
    

• Edit Example Copy

  Fetch the details for a specific geospatial object - https://layers.nbnatlas.org/ws/object/{pid}   https://layers.nbnatlas.org/ws/object/{pid}

  GET JSON

  • GET
  • JSON

  Fetch the details for a specific object using its primary ID pid. The results include name, description, bounding box, area, etc.

  Examples

  • Edit

    The ACT object for West Norfolk

    Fetch the details for object pid=2628 (e.g. from fid=cl14)

    URL: https://layers.nbnatlas.org/ws/object/2628
    

• Edit Example Copy

  Download a shape object as KML - https://layers.nbnatlas.org/ws/shape/kml/{pid}   https://layers.nbnatlas.org/ws/shape/kml/{pid}

  GET XML

  • GET
  • XML

  Download the object as KML using its primary ID pid.

  Examples

  • Edit

    KML for Glamorganshire

    Fetch the KML for Glamorganshire using the pid.

    URL: https://layers.nbnatlas.org/ws/shape/kml/2730.kml
    

• Edit Example Copy

  Download a shape object as WKT - https://layers.nbnatlas.org/ws/shape/wkt/{pid}   https://layers.nbnatlas.org/ws/shape/wkt/{pid}

  GET JSON

  • GET
  • JSON

  Download a shape object as well-known text (WKT) using its primary ID pid.

  Examples

  • Edit

    WKT shape for Glamorganshire

    Download the WKT shape for Glamorganshire using its pid.

    URL: https://layers.nbnatlas.org/ws/shape/wkt/2730.wkt
    

• Edit Example Copy

  Download a shape object as GeoJSON - https://layers.nbnatlas.org/ws/shape/geojson/{pid}   https://layers.nbnatlas.org/ws/shape/geojson/{pid}

  GET JSON

  • GET
  • JSON

  Download a shape object as GeoJSON using its primary ID pid.

  Examples

  • Edit

    GeoJSON shape for Glamorganshire

    Download the GeoJSON shape for Glamorganshire using its pid.

    URL: https://layers.nbnatlas.org/ws/shape/geojson/2730
    

• Edit Example Copy

  Download a shape object as a ESRI Shape file - https://layers.nbnatlas.org/ws/shape/shp/{pid}   https://layers.nbnatlas.org/ws/shape/shp/{pid}

  GET ZIP

  • GET
  • ZIP

  Download a shape object as an ESRI Shape file. Note that the data is packaged in a zip file that contains all of the separate files to support a "shape file."

  Examples

  • Edit

    Shape file for Glamorganshire

    Download the a shape (zip) file for Glamorganshire using its pid. The zip file contains the 6 individual component files that make a "shape" file.

    URL: https://layers.nbnatlas.org/ws/shape/shp/2730.zip
    

• Edit Example Copy

  Upload geometry as WKT - https://layers.nbnatlas.org/ws/shape/upload/wkt   https://layers.nbnatlas.org/ws/shape/upload/wkt

  POST JSON

  • POST
  • JSON

  Upload a geometry object formatted in WKT. A JSON object with the new primary ID (pid) is returned if successful.

  wkt *	String	The WKT string describing the shape
  name	String	The name of the object
  description	String	The description of the object
  user_id	Integer	The User ID associated with the API key
  api_key	String	Spatial portal's API key

• Edit Example Copy

  Upload geometry as GeoJSON - https://layers.nbnatlas.org/ws/shape/upload/geojson   https://layers.nbnatlas.org/ws/shape/upload/geojson

  POST JSON

  • POST
  • JSON

  Upload a geometry object as a GeoJSON string. A JSON object with the new primary ID (pid) is returned if successful.

  description	String	The description of the object
  name	String	The name of the object
  geojson *	String	The GeoJSON string describing the shape
  api_key	String	Spatial portal's API key
  user_id	Integer	The User ID associated with the API key

• Edit Example Copy

  Upload geometry as a point and radius - https://layers.nbnatlas.org/ws/shape/upload/{lat}/{lng}/{radius}   https://layers.nbnatlas.org/ws/shape/upload/{lat}/{lng}/{radius}

  POST JSON

  • POST
  • JSON

  Upload/create a geometry object as a circle: a point (lat, lng) and radius. A JSON object with the new primary ID pid is returned if successful.

  user_id	Integer	The User ID associated with the API key
  name	String	The name of the object
  api_key	String	Spatial portal's API key
  description	String	The description of the object

• Edit Example Copy

  Upload shapefile (Multipart) - https://layers.nbnatlas.org/ws/shape/upload/shp   https://layers.nbnatlas.org/ws/shape/upload/shp

  POST JSON

  • POST
  • JSON

  Upload a shapefile into the Atlas. The shapefile (archived as a zip file) is sent as the multipart form data. If successful a JSON object is returned with the ID of the shapefile (shp_id) and an array of features (id, name).

  user_id *	Integer	The User ID associated with the API key
  api_key *	String	Spatial portal's API key

• Edit Example Copy

  Upload shapefile (Regular) - https://layers.nbnatlas.org/ws/shape/upload/shp   https://layers.nbnatlas.org/ws/shape/upload/shp

  POST JSON

  • POST
  • JSON

  Upload a shapefile into the Atlas. The shapefile (archived as a zip file) is sent as the multipart form data. If successful a JSON object is returned with the ID of the shapefile (shp_id) and an array of features (id, name).

  user_id *	Integer	The User ID associated with the API key
  api_key *	String	Spatial portal's API key
  shp_file_url	String	Url

• Edit Example Copy

  Create object from shapefile feature - https://layers.nbnatlas.org/ws/shape/upload/shp/{shp_id}/{feature_id}   https://layers.nbnatlas.org/ws/shape/upload/shp/{shp_id}/{feature_id}

  POST JSON

  • POST
  • JSON

  The second step of adding shapefile to the Atlas: once a shapefile ( shp_id ) has been uploaded, the features ( feature_id ) in the file can be converted into spatial objects. If successful return a Upload a shapefile into the Atlas. If successful a JSON object is returned with the primary ID of the object: { "id" : 3742602}

  api_key *	String	Spatial portal's API key
  shp_id *	String	The ID returned when uploading a shapefile
  user_id *	Integer	The User ID associated with the API key
  feature_id *	String	The ID number of the shapefile's feature to import into the Atlas. The IDs are returned when the shapefile is uploaded
  name *	String	The name of the geometry object
  description *	String	The description of the object

• Edit Example Copy

  Update object from shapefile feature - https://layers.nbnatlas.org/ws/shape/upload/shp/{pid}/{shp_id}/{feature_id}   https://layers.nbnatlas.org/ws/shape/upload/shp/{pid}/{shp_id}/{feature_id}

  POST JSON

  • POST
  • JSON

  Update an existing geospatial object ( pid ) from a feature in a shapefile ( shp_id/feature_id ). If successful, a JSON object will be returned: { 'updated' : true}

  user_id *	Integer	The User ID associated with the API key
  feature_id *	String	The ID number of the shapefile's feature to import into the Atlas. The IDs are returned when the shapefile is uploaded
  shp_id *	String	The ID returned when uploading a shapefile
  description *	String	The description of the object
  name *	String	The name of the geometry object
  api_key *	String	Spatial portal's API key
  pid	String	The primary ID of the object to be updated

• Edit Example Copy

  Intersect a layer(s) at a given set of coordinates - https://layers.nbnatlas.org/ws/intersect/{id}/{latitude}/{longitude}   https://layers.nbnatlas.org/ws/intersect/{id}/{latitude}/{longitude}

  GET JSON

  • GET
  • JSON

  Multiple field ids or layer names can be specified separated by a comma (e.g. cl22,cl23):

  Examples

  • Edit

    Reverse geocode Watsonian Vice County

    Lookup Watsonian Vice County from GPS

    URL: https://layers.nbnatlas.org/ws/intersect/cl14/51.5074/0.1278
    

• Edit Example Copy

  Batch intersect a layer(s) at given coordinates - https://layers.nbnatlas.org/ws/intersect/batch   https://layers.nbnatlas.org/ws/intersect/batch

  POST JSON

  • POST
  • JSON

  Multiple field ids or layer names can be specified separated by a comma (e.g. cl22,cl23). Limited to 1000 coordinates

  Example output

  POST: https://layers.nbnatlas.org/ws/intersect/batch
  Body: fids=cl14&points=51.5074,0.1278,52.5074,0.1278
  
  {"progress":0,"status":"waiting","waiting":"In queue","batchId":"1489494775565","statusUrl":"https://layers.nbnatlas.org/ws/intersect/batch/1489494775565","points":2,"fields":1}
  
  GET: https://layers.nbnatlas.org/ws/intersect/batch/1489494775565
  
  {"progress":2,"progressMessage":"Finished sampling layer: county_coastal_terrestrial_region. Points processed: 1","status":"finished","downloadUrl":"https://layers.nbnatlas.org/ws/intersect/batch/download/1489494775565","finished":"14/03/17 12:32:55:860","points":2,"started":"14/03/17 12:32:55:565","fields":1}
  
  GET: https://layers.nbnatlas.org/ws/intersect/batch/download/1489494775565.zip
  
  unzip 1489494775565.zip
  
  Returns:
  
  latitude,longitude,cl14
  51.5074,0.1278,West Kent
  52.5074,0.1278,Cambridgeshire

  View : https://layers.nbnatlas.org/ws/intersect/batch

• Edit Example Copy

  Check batch intersect status with a batchId - https://layers.nbnatlas.org/ws/intersect/batch/{batchId}   https://layers.nbnatlas.org/ws/intersect/batch/{batchId}

  GET JSON

  • GET
  • JSON

  Multiple field ids or layer names can be specified separated by a comma (e.g. cl22,cl23). Limited to 1000 coordinates

  View : https://layers.nbnatlas.org/ws/intersect/batch/{batchId}

• Edit Example Copy

  Download a finished batch intersect - https://layers.nbnatlas.org/ws/intersect/batch/download/{batchId}   https://layers.nbnatlas.org/ws/intersect/batch/download/{batchId}

  GET CSV

  • GET
  • CSV

  Download a finished batch intersect with a batchId as zipped file

  View : https://layers.nbnatlas.org/ws/intersect/batch/download/{batchId}

Mapping - Creating maps with WMS services, static heat maps

• Edit Example Copy

  WMS Legend - https://records-ws.nbnatlas.org/mapping/legend   https://records-ws.nbnatlas.org/mapping/legend

  GET CSV

  • GET
  • CSV

  Returns a table of values to allow a legend to be generated by the client.

  q *	String	Query of the form field:value e.g. q=genus:Macropus or a free text search e.g. q=Macropus
  fq	String	Filters to be applied to the original query. These are additional params of the form fq=INDEXEDFIELD:VALUE e.g. fq=kingdom:Fungi. See https://records-ws.nbnatlas.org/index/fields for all the fields that a queryable.
  lat	Double	The decimal latitude to limit records to. Use with lon and radius to specify a "search" circle
  lon	Double	The decimal latitude to limit records to. Use with lon and radius to specify a "search" circle
  radius	Double	The radius in which to limit records (relative to the lat, lon point). Use with lat and lon to specify a "search" circle.
  wkt	String	The polygon area in which to limit records. For information on Well known text
  cm *	String	Colour mode - facet to use for generating the colour gradations
  type	String	Response type. "application/csv" (default), or "application/json".

  Examples

  • Edit

    Species legend for macropus.

    Legend for WMS q=macropus with cm=species as JSON.

    URL: https://records-ws.nbnatlas.org/mapping/legend?q=macropus&cm=species&type=application/json
    

• Edit Example Copy

  WMS GetCapabilities - https://records-ws.nbnatlas.org/ogc/ows   https://records-ws.nbnatlas.org/ogc/ows

  GET XML

  • GET
  • XML

  [Attention: WMS Calls are currently under review - 14/3/2017]
  Web Mapping Service GetCapabilities. This is an OGC service that can be used to retrieve a listing of layers for taxa in a hierarchical format in XML.

  q	String	Query of the form field:value e.g. q=genus:Macropus or a free text search e.g. q=Macropus
  fq	String	Filters to be applied to the original query. These are additional params of the form fq=INDEXEDFIELD:VALUE e.g. fq=kingdom:Fungi. See https://records-ws.nbnatlas.org/index/fields for all the fields that a queryable.
  facet	String	Supported values are "off" or "on". By default, its "on". This is worth switching off if facetting is not required, to reduce the JSON being sent.
  facets	String	Comma separated list of the fields to create facets on e.g. facets=basis_of_record.
  pageSize	Integer	Number of records to return
  startIndex	Integer	Record offset, to enable paging
  sort	Integer	The indexed field to sort by
  dir	Integer	Supports "asc" or "desc"
  flimit	Integer	Maximum number of facet values to return
  fsort	Integer	Method in which to sort the facets either "count" or "index"
  foffset	Integer	Facet offset, to enable paging
  fprefix	Integer	Limits facets to values that start with the supplied value
  lat	Double	The decimal latitude to limit records to. Use with lon and radius to specify a "search" circle
  lon	Double	The decimal latitude to limit records to. Use with lon and radius to specify a "search" circle
  radius	Double	The radius in which to limit records (relative to the lat, lon point). Use with lat and lon to specify a "search" circle.
  wkt	String	The polygon area in which to limit records. For information on Well known text

• Edit Example Copy

  WMS GetMetadata - https://records-ws.nbnatlas.org/ogc/getMetadata   https://records-ws.nbnatlas.org/ogc/getMetadata

  GET XML

  • GET
  • XML

  [Attention: WMS Calls are currently under review - 14/3/2017]
  

  q	String	Query of the form field:value e.g. q=genus:Macropus or a free text search e.g. q=Macropus
  fq	String	Filters to be applied to the original query. These are additional params of the form fq=INDEXEDFIELD:VALUE e.g. fq=kingdom:Fungi. See https://records-ws.nbnatlas.org/index/fields for all the fields that a queryable.
  facet	String	Supported values are "off" or "on". By default, its "on". This is worth switching off if facetting is not required, to reduce the JSON being sent.
  facets	String	Comma separated list of the fields to create facets on e.g. facets=basis_of_record.
  pageSize	Integer	Number of records to return
  startIndex	Integer	Record offset, to enable paging
  sort	Integer	The indexed field to sort by
  dir	Integer	Supports "asc" or "desc"
  flimit	Integer	Maximum number of facet values to return
  fsort	Integer	Method in which to sort the facets either "count" or "index"
  foffset	Integer	Facet offset, to enable paging
  fprefix	Integer	Limits facets to values that start with the supplied value
  lat	Double	The decimal latitude to limit records to. Use with lon and radius to specify a "search" circle
  lon	Double	The decimal latitude to limit records to. Use with lon and radius to specify a "search" circle
  radius	Double	The radius in which to limit records (relative to the lat, lon point). Use with lat and lon to specify a "search" circle.
  wkt	String	The polygon area in which to limit records. For information on Well known text

• Edit Example Copy

  Generate static map - https://records-ws.nbnatlas.org/mapping/wms/image   https://records-ws.nbnatlas.org/mapping/wms/image

  GET PNG

  • GET
  • PNG

  Generate a static image with various formatting options.

  fq	String	Filters to be applied to the original query. These are additional params of the form fq=INDEXEDFIELD:VALUE e.g. fq=kingdom:Fungi. See https://records-ws.nbnatlas.org/index/fields for all the fields that a queryable.
  q	String	Query of the form field:value e.g. q=genus:Macropus or a free text search e.g. q=Macropus
  format	String	Default 'jpg'
  widthmm	String	Image width in mm
  pradiusmm	String	Species point radius in mm, integer
  pradiuspx	String	Species point radius in pixels, integer. Only pradiuspx or pradiusmm need be supplied. If both supplied, pradiuspx takes precendence.
  pcolour	String	Point colour in hex. Default is FF0000
  popacity	String	Point opacity. Default is 0.8
  baselayer	String	Base layer to use from http://spatial.ala.org.au/geoserver
  baselayerPrefix	String	Default "ALA:"
  scale	String	Include a scale. DefaultValue = "off".
  dpi	String	Dots per inch. Default is 300.
  outline	String	Point outline. Default is false
  outlineColour	String	Default #000000
  fileName	String	File name to use
  extents	String	minx,miny,maxx,maxy (EPSG:4326) e.g. -11.2538,48.6754,3.0270,60.7995

  Examples

  • Edit

    Download Black Redstart static map

    Map on the UK showing sighting of Black Redstart

    URL: https://records-ws.nbnatlas.org/mapping/wms/image?baselayer=world&format=jpg&pcolour=3531FF&scale=on&popacity=1&q=*:*&fq=lsid:NHMSYS0000530744&extents=-11.2538,48.6754,3.0270,60.7995&outline=true&outlineColour=0x000000&pradiusmm=1&dpi=300
    

• Edit Example Copy

  WMS GetFeatureInfo - https://records-ws.nbnatlas.org/ogc/getFeatureInfo   https://records-ws.nbnatlas.org/ogc/getFeatureInfo

  GET XML

  • GET
  • XML

  [Attention: WMS Calls are currently under review - 14/3/2017]

  q	String	Query of the form field:value e.g. q=genus:Macropus or a free text search e.g. q=Macropus
  fq	String	Filters to be applied to the original query. These are additional params of the form fq=INDEXEDFIELD:VALUE e.g. fq=kingdom:Fungi. See https://records-ws.nbnatlas.org/index/fields for all the fields that a queryable.
  facet	String	Supported values are "off" or "on". By default, its "on". This is worth switching off if facetting is not required, to reduce the JSON being sent.
  facets	String	Comma separated list of the fields to create facets on e.g. facets=basis_of_record.
  pageSize	Integer	Number of records to return
  startIndex	Integer	Record offset, to enable paging
  sort	Integer	The indexed field to sort by
  dir	Integer	Supports "asc" or "desc"
  flimit	Integer	Maximum number of facet values to return
  fsort	Integer	Method in which to sort the facets either "count" or "index"
  foffset	Integer	Facet offset, to enable paging
  fprefix	Integer	Limits facets to values that start with the supplied value
  lat	Double	The decimal latitude to limit records to. Use with lon and radius to specify a "search" circle
  lon	Double	The decimal latitude to limit records to. Use with lon and radius to specify a "search" circle
  radius	Double	The radius in which to limit records (relative to the lat, lon point). Use with lat and lon to specify a "search" circle.
  wkt	String	The polygon area in which to limit records. For information on Well known text

• Edit Example Copy

  WMS GetMap - https://records-ws.nbnatlas.org/ogc/wms/reflect   https://records-ws.nbnatlas.org/ogc/wms/reflect

  GET PNG

  • GET
  • PNG

  WMS services for point occurrence data

  q	String	Query of the form field:value e.g. q=genus:Macropus or a free text search e.g. q=Macropus
  fq	String	Filters to be applied to the original query. These are additional params of the form fq=INDEXEDFIELD:VALUE e.g. fq=kingdom:Fungi. See https://records-ws.nbnatlas.org/index/fields for all the fields that a queryable.
  facet	String	Supported values are "off" or "on". By default, its "on". This is worth switching off if facetting is not required, to reduce the JSON being sent.
  facets	String	Comma separated list of the fields to create facets on e.g. facets=basis_of_record.
  pageSize	Integer	Number of records to return
  startIndex	Integer	Record offset, to enable paging
  sort	Integer	The indexed field to sort by
  dir	Integer	Supports "asc" or "desc"
  flimit	Integer	Maximum number of facet values to return
  fsort	Integer	Method in which to sort the facets either "count" or "index"
  foffset	Integer	Facet offset, to enable paging
  fprefix	Integer	Limits facets to values that start with the supplied value
  lat	Double	The decimal latitude to limit records to. Use with lon and radius to specify a "search" circle
  lon	Double	The decimal latitude to limit records to. Use with lon and radius to specify a "search" circle
  radius	Double	The radius in which to limit records (relative to the lat, lon point). Use with lat and lon to specify a "search" circle.
  wkt	String	The polygon area in which to limit records. For information on Well known text
  ENV	String	Additional parameters. e.g. ENV=color%3Acd3844%3Bsize%3A3%3Bopacity%3A0.8. color - hex RGB values. e.g. colour:cd3844. size - radius of points in pixels. opacity - opacity value 0 - 1. sel - fq parameter applied to CQL_FILTER. Matching occurrences will be highlighted on the map in a Red circle. uncertainty - presence of the uncertainty parameter draws uncertainty circles to a fixed maximum of 30km. colormode - facet colouring type. -1 (default) use color value. grid map as density grid. Grid cells drawn are not restricted to within any query WKT parameters. facetname colour as categories in a facet. facetname,cutpoints colour as range in a facet using the supplied comma separated cutpoints. 4 to 10 values are required. Include minimum and maximum. Minimum and maximum values do not need to be accurate. e.g. colormode:year,1800,1900,1950,1970,1990,2010 Please see the examples for more available ENV parameters

  Examples

  • Edit

    OSGB36 (ESPG:27700) Leaflet map with multiple grid displays (Vice County Layer)

    Standalone leaflet JS example that displays maps and grids in the OSGB36 projection.

    URL: https://records-ws.nbnatlas.org/ogc/wms/reflect
    Online demo: https://duncanrowland.github.io/NBNMapOverlayExamples/leaflet3.html
    

  • Edit

    Single Species Layer with LeafletJS

    An example showing one layer overlay using leafletjs.

    URL: https://records-ws.nbnatlas.org/ogc/wms/reflect
    Online demo: https://duncanrowland.github.io/NBNMapOverlayExamples/leaflet1.html
    

  • Edit

    OSGB36 (ESPG:27700) Leaflet map with multiple grid displays (OS Layer)

    Standalone leaflet JS example that displays maps and grids in the OSGB36 projection.

    URL: https://records-ws.nbnatlas.org/ogc/wms/reflect
    Online demo: https://s3.eu-west-2.amazonaws.com/nbnatlas-dev/map-test-OS-variants.html
    

Endemism - Services for reports on endemism for an area

• Edit Example Copy

  Count endemic species - https://records-ws.nbnatlas.org/explore/counts/endemic   https://records-ws.nbnatlas.org/explore/counts/endemic

  GET JSON

  • GET
  • JSON

  Count of distinct endemic species within an area (* indicates required params)

  q *	String	The initial query. q=: will query anything, q=macropus will do a free text search for macropus, q=kingdom:Fungi will search for records with a kingdom of Fungi. For a listing of the fields that can be queried in a q=INDEXEDFIELD:VALUE fashion, see /index/fields. This will restrict the records that are considered in then region. For example this could allow people to restrict the service to endemic birds.
  fq	String	Filters to be applied to the original query. These are additional params of the form fq=INDEXEDFIELD:VALUE e.g. fq=kingdom:Fungi. See https://records-ws.nbnatlas.org/index/fields for all the fields that a queryable.
  wkt *	String	The Well Known Text Area in which to provide the endemic species.
  facets *	String	The field on which to based the species list. This can be taxon_concept_lsid or species_guid

  Examples

  • Edit

    Count endemics

    Count all the endemic species recorded within a small area in London.
    (Note, wkt POLYGON=lon,lat and not lat,lon).

    URL: https://records-ws.nbnatlas.org/explore/counts/endemic?wkt=POLYGON((0.12+51.50,0.13+51.50,0.13+51.51,0.12+51.51,0.12+51.50))&q=*:*&facets=species_guid
    

• Edit Example Copy

  Endemic Species list - https://records-ws.nbnatlas.org/explore/endemic/species   https://records-ws.nbnatlas.org/explore/endemic/species

  GET JSON

  • GET
  • JSON

  List endemic species within an area (* indicates required params)

  q *	String	The initial query. q=: will query anything, q=macropus will do a free text search for macropus, q=kingdom:Fungi will search for records with a kingdom of Fungi. For a listing of the fields that can be queried in a q=INDEXEDFIELD:VALUE fashion, see /index/fields. This will restrict the records that are considered in then region. For example this could allow people to restrict the service to endemic birds.
  fq	String	Filters to be applied to the original query. These are additional params of the form fq=INDEXEDFIELD:VALUE e.g. fq=kingdom:Fungi. See https://records-ws.nbnatlas.org/index/fields for all the fields that a queryable.
  wkt *	String	The Well Known Text Area in which to provide the endemic species.
  facets *	String	The field on which to based the species list. This can be taxon_concept_lsid or species_guid

  Examples

  • Edit

    List endemics (JSON)

    List (in JSON) all the endemic species recorded within a small area in London. (Note, wkt POLYGON=lon,lat and not lat,lon).

    URL: https://records-ws.nbnatlas.org/explore/endemic/species?wkt=POLYGON((0.12+51.50,0.13+51.50,0.13+51.51,0.12+51.51,0.12+51.50))&q=*:*&facets=species_guid
    

• Edit Example Copy

  Endemic Species list (CSV) - https://records-ws.nbnatlas.org/explore/endemic/species.csv   https://records-ws.nbnatlas.org/explore/endemic/species.csv

  GET CSV

  • GET
  • CSV

  List endemic species within an area

  q	String	The initial query. q=: will query anything, q=macropus will do a free text search for macropus, q=kingdom:Fungi will search for records with a kingdom of Fungi. For a listing of the fields that can be queried in a q=INDEXEDFIELD:VALUE fashion, see /index/fields. This will restrict the records that are considered in then region. For example this could allow people to restrict the service to endemic birds.
  fq	String	Filters to be applied to the original query. These are additional params of the form fq=INDEXEDFIELD:VALUE e.g. fq=kingdom:Fungi. See https://records-ws.nbnatlas.org/index/fields for all the fields that a queryable.
  wkt	String	The Well Known Text Area in which to provide the endemic species.
  facets	String	The field on which to based the species list. This can be taxon_concept_lsid or species_guid

  Examples

  • Edit

    List endemics (CSV)

    List (in a CSV file) all the endemic species recorded within a small area in London. (Note, wkt POLYGON=lon,lat and not lat,lon).

    URL: https://records-ws.nbnatlas.org/explore/endemic/species.csv?wkt=POLYGON((0.12+51.50,0.13+51.50,0.13+51.51,0.12+51.51,0.12+51.50))&q=*:*&facets=species_guid
    

Parsing - Services for parsing ad hoc occurrence data

• Edit Example Copy

  Match darwin core terms - https://records-ws.nbnatlas.org/parser/matchTerms   https://records-ws.nbnatlas.org/parser/matchTerms

  POST JSON

  • POST
  • JSON

  Accepts a POST JSON body.

  Example 1:

  
  ["scientific name", "latitude"] 
  

  Will return the following darwin core terms in JSON

   ["scientificName", "decimalLatitude"] 

  Example 2:

  
  ["Robin", "12.2", "149.0"] 
  

  Will return the following darwin core terms in JSON

   ["vernacularName", "decimalLatitude","decimalLongitude"] 

  View : https://records-ws.nbnatlas.org/parser/matchTerms

• Edit Example Copy

  Test darwin core terms - https://records-ws.nbnatlas.org/parser/areDwcTerms   https://records-ws.nbnatlas.org/parser/areDwcTerms

  POST JSON

  • POST
  • JSON

  Accepts a POST JSON body.

  Example 1:

  
  ["scientific name"] 
  

  Will return: true

  Example 2:

  
  ["Robin"] 
  

  Will return: false

  View : https://records-ws.nbnatlas.org/parser/areDwcTerms

• Edit Example Copy

  Ad hoc processing - https://records-ws.nbnatlas.org/process/adhoc   https://records-ws.nbnatlas.org/process/adhoc

  POST JSON

  • POST
  • JSON

  Accepts a POST JSON body.

  Example 1:

  
  { "vernacularName": "Robin" } 
  

  Will return the following darwin core terms in JSON

   {"values":[{"processed":"None","raw":"None","name":"originalSensitiveValues"},{"processed":"present","raw":"","name":"occurrenceStatus"},{"processed":"UNKNOWN","raw":"","name":"nameParseType"},{"processed":"Erithacus rubecula","raw":"","name":"species"},{"processed":"vernacularMatch","raw":"","name":"nameMatchMetric"},{"processed":"Continental Robin","raw":"Robin","name":"vernacularName"}...etc.. 

  View : https://records-ws.nbnatlas.org/process/adhoc

• Edit Example Copy

  Map darwin core terms - https://records-ws.nbnatlas.org/parser/mapTerms   https://records-ws.nbnatlas.org/parser/mapTerms

  POST JSON

  • POST
  • JSON

  Maps supplied terms to darwin core terms. Returns a map in JSON format with the supplied values as keys and matched terms as values.
  

  Sent:

   ["lat","long","sci name"] 

  Received:

   {  "lat":"decimalLatitude",  "long":"decimalLongitude",  "sci name":"scientificName" } 

  View : https://records-ws.nbnatlas.org/parser/mapTerms

Data resources - Data resource metadata including taxonomic scope, attribution

• Edit Example Copy

  Data licences - https://registry.nbnatlas.org/ws/licence   https://registry.nbnatlas.org/ws/licence

  GET JSON

  • GET
  • JSON

  Returns a JSON list of licences recognised by the Atlas.

  View : https://registry.nbnatlas.org/ws/licence

• Edit Example Copy

  List data resources - https://registry.nbnatlas.org/ws/dataResource   https://registry.nbnatlas.org/ws/dataResource

  GET JSON

  • GET
  • JSON

  List data resources in JSON

  View : https://registry.nbnatlas.org/ws/dataResource

• Edit Example Copy

  Data resource metadata - https://registry.nbnatlas.org/ws/dataResource/{uid}   https://registry.nbnatlas.org/ws/dataResource/{uid}

  GET JSON

  • GET
  • JSON

  Data resource metadata

  uid

  String

  The UID of the institution.

  Examples

  • Edit

    Show metadata

    Metadata for "A Conservation Evaluation of British Lichens and Lichenicolous Fungi" (i.e. data resource dr559)

    URL: https://registry.nbnatlas.org/ws/dataResource/dr559
    

• Edit Example Copy

  Get List Metadata - https://lists.nbnatlas.org/ws/speciesList/{druid}   https://lists.nbnatlas.org/ws/speciesList/{druid}

  GET JSON

  • GET
  • JSON

  Returns the metadata associated with a species list.

  Examples

  • Edit

    Metadata for list

    Metadata for list with druid dr577

    URL: https://lists.nbnatlas.org/ws/speciesList/dr577
    

Data providers - Data provider metadata including taxonomic scope, attribution

• Edit Example Copy

  List data providers - https://registry.nbnatlas.org/ws/dataProvider   https://registry.nbnatlas.org/ws/dataProvider

  GET JSON

  • GET
  • JSON

  List data providers

  View : https://registry.nbnatlas.org/ws/dataProvider

Auto complete - Services that support autocomplete text boxes

• Edit Example Copy

  Auto complete Search (occurrence based names) - https://records-ws.nbnatlas.org/autocomplete/search   https://records-ws.nbnatlas.org/autocomplete/search

  GET JSON

  • GET
  • JSON

  Used to provide a list of scientific names that can be used to automatically complete a supplied partial name for use in searching for records in the occurrence records system.

  q *	String	Input query
  fq	String	Filter query that is used to determine occurrence counts
  pageSize	Integer	Max number of results to return
  all	Boolean	Set this to true to include matches with 0 occurrences found
  counts	Boolean	Set this to false to exclude occurrence counts
  synonyms	Boolean	Set this to false to exclude synonym matches

  Examples

  • Edit

    Search for vulpe...

    Return matches with no occurences

    URL: https://records-ws.nbnatlas.org/autocomplete/search?q=vulpe&all=true
    

• Edit Example Copy

  Auto Complete Search - https://species-ws.nbnatlas.org/search/auto   https://species-ws.nbnatlas.org/search/auto

  GET JSON

  • GET
  • JSON

  Used to provide a list of scientific and common names that can be used to automatically complete a supplied partial name.

  q *	String	The value to auto complete e.g. q=Mac
  geoOnly	String	When "true" only include results that have some geospatial occurrence records
  idxType	String	The index type to limit . Values include: * TAXON * REGION * COLLECTION * INSTITUTION * DATASET
  limit	String	The maximum number of results to return (default = 10)

  Examples

  • Edit

    Search taxa starts for autocomplete

    Search for taxa starting with "Mac"

    URL: https://species-ws.nbnatlas.org/search/auto?q=Mac
    

General data - General data

• Edit Example Copy

  Data licences - https://registry.nbnatlas.org/ws/licence   https://registry.nbnatlas.org/ws/licence

  GET JSON

  • GET
  • JSON

  Returns a JSON list of licences recognised by the Atlas.

  View : https://registry.nbnatlas.org/ws/licence

• Edit Example Copy

  Get a summary for an entity - https://registry.nbnatlas.org/ws/lookup/summary/{uid}   https://registry.nbnatlas.org/ws/lookup/summary/{uid}

  GET JSON

  • GET
  • JSON

  Get a summary information for an entity

  Examples

  • Edit

    Lookup entity

    Entity with uid dp58

    URL: https://registry.nbnatlas.org/ws/lookup/summary/dp58
    

• Edit Example Copy

  Get List Metadata - https://lists.nbnatlas.org/ws/speciesList/{druid}   https://lists.nbnatlas.org/ws/speciesList/{druid}

  GET JSON

  • GET
  • JSON

  Returns the metadata associated with a species list.

  Examples

  • Edit

    Metadata for list

    Metadata for list with druid dr577

    URL: https://lists.nbnatlas.org/ws/speciesList/dr577
    

• Edit Example Copy

  Data licences - https://registry.nbnatlas.org/ws/licence   https://registry.nbnatlas.org/ws/licence

  GET JSON

  • GET
  • JSON

  Returns a JSON list of licences recognised by the Atlas.

  View : https://registry.nbnatlas.org/ws/licence

Breakdowns - Supplies breakdown information about records.

• Edit Example Copy

  Collectory breakdown - https://records-ws.nbnatlas.org/breakdown/{collectorytype}/{uid}   https://records-ws.nbnatlas.org/breakdown/{collectorytype}/{uid}

  GET JSON

  • GET
  • JSON

  Performs a breakdown of the supplied collectory type.

  max	Integer	The maximum number of names to include in the breakdown. When this value is supplied the breakdown will traverse up the taxonomic hierarchy until a maximum of max names is discovered. Thus the rank of the breakdown is calculated by this service and should not be provided.
  name	String	The scientific name to limit the breakdown to - needs a valid rank to be supplied
  rank	String	The rank at which to perform the breakdown. If a name is specified in conjunction to this the breakdown will be performed at the next level further limiting the query.

  Examples

  • Edit

    Breakdown collectory and return counts

    Breakdown collectory by phylum

    URL: https://records-ws.nbnatlas.org/breakdown/dataResources/dr495?rank=phylum
    

Species lists - Species lists webservices

Webservices for storage and creation and querying of lists

• Edit Example Copy

  Retrieve metadata for all lists - https://lists.nbnatlas.org/ws/speciesList   https://lists.nbnatlas.org/ws/speciesList

  GET JSON

  • GET
  • JSON

  Service to retrieve the metadata for all lists. This includes parameters to page through the lists.

  user	String	The CAS username. This will allow the list to be order in a manner that places all the lists owed by the supplied user first.
  sort	String	The list metadata on which to sort the lists. Use one of the following: listName, username, listType, count
  order	String	The order in which to perform the sort. Either asc or desc
  offset	Integer	The offset at which to start the page. This parameter along with the max param supplies the support for paging. The default value is 0.
  max	Integer	The maximum number of records to return in a page of results. The default value is 25

  Examples

  • Edit

    Metadata for all lists

    Default parameters

    URL: https://lists.nbnatlas.org/ws/speciesList
    

• Edit Example Copy

  Create List - https://lists.nbnatlas.org/ws/speciesList   https://lists.nbnatlas.org/ws/speciesList

  POST

  • POST

  Creates a new species list with the information supplied in the JSON body of the post. At the moment this service does not accept properties for list items. This will probably need to be implement as a different service.

  listName	String	The name for the list
  listItems	String	A comma separated list of species to include on the list
  listType	String	The type of list: SPECIES_CHARACTERS, CONSERVATION_LIST, SENSITIVE_LIST, LOCAL_LIST, COMMON_TRAIT, COMMON_HABITAT, SPATIAL_PORTAL, TEST, OTHER
  description	String	A description of the list

  Example output

  Returns the druid for the newly created list in the response header.

• Edit Example Copy

  Species List Items - https://lists.nbnatlas.org/ws/speciesListItems/{dataResourceUid}   https://lists.nbnatlas.org/ws/speciesListItems/{dataResourceUid}

  GET JSON

  • GET
  • JSON

  Returns all the items that are on the supplied species list.

  Examples

  • Edit

    List items for species list

    Retrieve all the scientific names and matched lsids for species list dr633

    URL: https://lists.nbnatlas.org/ws/speciesListItems/dr633
    

• Edit Example Copy

  Species Lists for Species - https://lists.nbnatlas.org/ws/species/{guid}   https://lists.nbnatlas.org/ws/species/{guid}

  GET JSON

  • GET
  • JSON

  Returns all the lists and supplied properties for the species of the supplied guid.

  Examples

  • Edit

    Species list for Homo Sapies

    All the list and key value pairs (KVP) for Homo Sapies

    URL: https://lists.nbnatlas.org/ws/species/NHMSYS0000376773