The mapping API is a web map tile service making it straightforward to visualize GBIF content on interactive maps, and overlay content from other sources.
The following features are supported:
- Map layers are available for a country, dataset, taxon (species, subspecies or higher taxon), publisher or publishing country. These layers can be filtered by year range and basis of record.
- 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.
Two tile formats are available: vector tiles and raster tiles. The raster tiles are generated from the vector tiles.
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:
With the following parameters:
|source||Either density for fast, precalculated tiles, or adhoc for any search.|
|z, x, y||the zoom, column and row|
|srs||Spatial reference system. One of:
|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.|
Without any additional parameters, all occurrences will be returned.
One primary search parameter is permitted, from these:
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.
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.
Vector styles must be coloured by the client — you decide!
Raster styles are predefined. Set
style= to one of the following: