GBIF maps API

Feature overview

Birds (Aves) in Australia.

The following features are supported:

Map layers are available for a country, dataset, taxon (including species, subspecies or higher taxon), publisher, publishing country or network. These layers can be filtered by year range, basis of record and country.
Data is returned as points, or "binned" into hexagons or squares.
Four map projections are supported.
Tiles are available in vector format for client styling, or raster format with predefined styles.
Arbitrary search terms are also supported, limited to a single projection and forced binning.

This service is intended for use with commonly used clients such as the OpenLayers or Leaflet Javascript libraries, Google Maps, or some GIS software. These libraries allow the GBIF layers to be visualized with other content, such as those coming from web map service (WMS) providers. It should be noted that the mapping API is not a WMS service, nor does it support WFS capabilities.

Tile formats

Two tile formats are available: vector tiles and raster tiles. The raster tiles are generated from the vector tiles.

A modern web browser can show either format. The styling of vector tiles is determined by client-side configuration (e.g. JavaScript); raster tiles are styled according to a limited set of GBIF styles. Point vector tiles are usually larger than an equivalent raster tile, and few JavaScript libraries can render them with acceptable speed. Simple vector tiles (few points, or any number of squares or hexagons) are small, fast to render, and can make zooming in and out smoother.

Vector tiles use Mapbox Vector Tile format, and contain a single layer occurrence. Objects in that layer are either points (default) or polygons (if chosen), each object has a total value; that is the number of occurrences at that point or in the polygon.

Raster tiles are provided in PNG format, and are normally 512px wide squares.

The tile URL format

The format of the URL is as follows:

https://api.gbif.org/v2/map/occurrence/{source}/{z}/{x}/{y}{format}?srs={srs}{params}

With the following parameters:

`source`	Either `density` for fast, precalculated tiles, or `adhoc` for any search.
`z`, `x`, `y`	the zoom, column and row
`format`	`.mvt` for a vector tile `@Hx.png` for a 256px raster tile (for legacy clients) `@1x.png` for a 512px raster tile `@2x.png` for a 1024px raster tile `@3x.png` for a 2048px raster tile `@4x.png` for a 4096px raster tile The larger raster tiles are intended for high resolution displays, e.g. 4K displays and many mobile phones.
`srs`	Spatial reference system. One of: EPSG:3857 (Web Mercator) EPSG:4326 (WGS84 plate careé) EPSG:3575 (Arctic LAEA) EPSG:3031 (Antarctic stereographic) see below under Projections.
`bin` (optional)	`square` or `hex` to aggregate occurrence counts into squares or hexagons. Points by default.
`hexPerTile` (optional)	sets the size of the hexagons (the number horizontally across a tile)
`squareSize` (optional)	sets the size of the squares. Choose a factor of 4096 so they tessalate correctly: probably from `8`, `16`, `32`, `64`, `128`, `256`, 512.
`style` (optional)	for raster tiles, choose from the available styles. Defaults to `classic.point`.
`params` (optional)	parameters from the occurrence API, e.g. `taxonKey`. See the next section.

Search parameters

Without any additional parameters, all occurrences will be returned.

One primary search parameter is permitted, from these: taxonKey, datasetKey, country, networkKey, publishingOrg, publishingCountry.

This can be combined with the parameter country, this limits the primary search to occurrences in that country.

An additional parameter year limits the occurrences within a range of years, for example 2000,2010.

The final parameter basisOfRecord can be given multiple times to include records with that basis of record. The full list is: OBSERVATION, HUMAN_OBSERVATION, MACHINE_OBSERVATION, MATERIAL_SAMPLE, PRESERVED_SPECIMEN, FOSSIL_SPECIMEN, LIVING_SPECIMEN, LITERATURE, UNKNOWN.

Ad-hoc queried tiles can have any query supported by the occurrence search API, but are much slower to retrieve, and are limited to WGS84 projection (see below). Prefer density tiles whenever possible.

Examples:

All occurrences — no additional parameters `https://api.gbif.org/v2/map/occurrence/density/{z}/{x}/{y}@1x.png?style=purpleYellow.point`
All birds (Aves) by small hexagons `https://api.gbif.org/v2/map/occurrence/density/{z}/{x}/{y}@1x.png?taxonKey=212&bin=hex&hexPerTile=30&style=classic-noborder.poly`
All birds observed by machine between 2015 and 2017 as squares `https://api.gbif.org/v2/map/occurrence/density/{z}/{x}/{y}@1x.png?taxonKey=212&basisOfRecord=MACHINE_OBSERVATION&years=2015,2017&bin=square&squareSize=128&style=purpleYellow-noborder.poly`
All preserved, fossil or living specimens from before 1900 published by Swedish publishers, in Arctic projection `https://api.gbif.org/v2/map/occurrence/density/{z}/{x}/{y}@1x.png?srs=EPSG:3575&publishingCountry=SE&basisOfRecord=PRESERVED_SPECIMEN&basisOfRecord=FOSSIL_SPECIMEN&basisOfRecord=LIVING_SPECIMEN&year=1600,1899&bin=square&squareSize=128&style=green.poly`
Ad-hoc query for occurrences with images, observed in January `https://api.gbif.org/v2/map/occurrence/adhoc/{z}/{x}/{y}@1x.png?srs=EPSG:4326&style=classic.poly&bin=square&squareSize=128&mediaType=StillImage&month=1`

Projections

The projection declares how coordinates on Earth are transformed to a two dimensional surface.

The tile schema defines how that two dimensional surface is split into smaller square images, and how those images are addressed.

Four projections are available for density tiles. Only the second, WGS84, is available for Ad-hoc tiles.

Information on the projections is on the GBIF base map tiles page.

Map styling

Vector styles must be coloured by the client — you decide!

Raster styles are predefined. Set style= to one of the following:

Capabilities endpoint

A summary of the data available for a density search is available using the capabilities endpoint. The URL format is

https://api.gbif.org/v2/map/occurrence/density/capabilities.json?{params}

where params is the same as for the tile URL query.

An query for https://api.gbif.org/v2/map/occurrence/density/capabilities.json?taxonKey=3759969& gives this result:

{
  "minLat": -34,
  "minLng": 16,
  "maxLat": -25,
  "maxLng": 25,
  "minYear": 1937,
  "maxYear": 1999,
  "total": 6,
  "generated": "2019-05-06T05:02Z"
}

showing the bounding box, year range, total and the time the map data was last recalculated.

Preview

A preview tool is in development. Meanwhile, look at the base map examples, raster style demos, MapboxGL demo and OpenLayers-based toolbox for examples.