Maps API

version v0.9

Mapping API

Quick Links

The mapping api is a web map tile service making it trivial to visualize GBIF content on interactive maps, and overlay content from other sources.

Developers familiar with tile mapping services should jump straight to the preview functionality

The following features are supported:

  • Map layers available for a country, dataset, taxon (species, subspecies or higher taxon), publisher
  • User defined styling by selecting a predefined color palette, or by providing styling rules
  • Density of content is clustered to a user defined cluster size (regardless of zoom level)
  • The ability to customise content shown by the basis of record (E.g. Specimens, Observations, Fossils etc)
  • For certain basis of record types, the time period may be customised by decade; e.g. map the observations of a species since 1970

This service is intended for use with commonly used clients such as the google maps api, leaflet JS library or the modest maps JS library. 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. The examples on this page use the leaflet library.

The tile URL format

The format of the url is as follows:

http://api.gbif.org/v0.9/map/density/tile?x={x}&y={y}&z={z}

With the following parameters:

type required A value of TAXON, DATASET, COUNTRY or PUBLISHER
key required The appropriate key for the chosen type (a taxon key, dataset/publisher uuid or 2 letter ISO country code)
resolution optional (default 1) The number of pixels to which density is aggregated. Valid values are 1, 2, 4, 8, and 16.
layer optional (multivalued) Declares the layers to be combined by the server for this tile. See Customizing layer content
palette optional Selects a predefined color palette. See styling a layer
colors optional Provides a user defined set of rules for coloring the layer. See styling a layer
saturation & hue optional Allows selection of a hue value between 0.0 and 1.0 when saturation is set to true. See styling a layer

Customizing layer content

The following layers may be used to instruct the server to combine the content into a single density layer. All layers declared will be combined by the server on rendering. Thus, for a given taxon, country, dataset or provider, it is possible to retrieve e.g:

  • A map of specimens only
  • A map of specimens and observations
  • A map of specimens only, and collected after 1970
  • A map of everything observed or collected after 2000
  • A map of everything where the year is known
  • A map of everything omitting those data known to be living specimens
  • ..etc

The quickest way to experiment with this is to use the preview functionality. The specification for the layers are provided below.

  • This is a multivalue field so it is expected that several layers are requested in any single URL
  • Should no layers be specified, a sensible default is provided. This is to preserve backwards compatibility since layering was an additional feature, and considered acceptable since a map with no layers makes little sense. At present the default returns all layers, but could be subject to future change (e.g. should a layer of records with known issues be added, it might not be included in the default)

Observations Observation layers can take no year (&layer=OBS_NO_YEAR), before the 1900s (&layer=OBS_PRE_1900) or any decade after 1900. The full list is given:

OBS_NO_YEAR, OBS_PRE_1900, OBS_1900_1910, OBS_1910_1920, OBS_1920_1930, OBS_1930_1940, OBS_1940_1950, OBS_1950_1960, OBS_1960_1970, OBS_1970_1980, OBS_1980_1990, OBS_1990_2000, OBS_2000_2010, OBS_2010_2020
Specimens Specimen layers can take no year (&layer=SP_NO_YEAR), before the 1900s (&layer=SP_PRE_1900) or any decade after 1900. The full list is given:

SP_NO_YEAR, SP_PRE_1900, SP_1900_1910, SP_1910_1920, SP_1920_1930, SP_1930_1940, SP_1940_1950, SP_1950_1960, SP_1960_1970, SP_1970_1980, SP_1980_1990, SP_1990_2000, SP_2000_2010, SP_2010_2020
Living If provided, the records with a declared basis of record of living will be included. LIVING
Fossil If provided, the records with a declared basis of record of fossil will be included. FOSSIL
Other Records where the basis of record is unknown, or something other than those above can take no year (&layer=OTH_NO_YEAR), before the 1900s (&layer=OTH_PRE_1900) or any decade after 1900. The full list is given:

OTH_NO_YEAR, OTH_PRE_1900, OTH_1900_1910, OTH_1910_1920, OTH_1920_1930, OTH_1930_1940, OTH_1940_1950, OTH_1950_1960, OTH_1960_1970, OTH_1970_1980,OTH_1980_1990, OTH_1990_2000, OTH_2000_2010, OTH_2010_2020

Styling a layer

Styling the configured layer is controlled through either the &colors parameter, the &palette parameter, or a combination of the &saturation and &hue parameters. If none are provided, a sensible default will be used, which may be subject to change without notice. The quickest way to experiment with this is to use the preview functionality.

Palette and Colors

The possible options for the palette are given:

Record count
0-10 10-100 100-1000 1000-10000 10000-100000 100000+
yellows_reds
blues
greens
greys
oranges
purples
reds

Should you wish to style a map further, you may provide a color ruleset using the &colors parameter. A ruleset is a pipe(|) separated series of rules, where each rule is comma (,) separated containing the min (optional and inclusive), max(optional and exclusive) and color to apply for the range. Colors are in #RGBA format (red, green, blue, alpha with a preceding hash). The ruleset must be URL encoded (in javascript, the encodeURIComponent() provides this). Thus, the format of the ruleset is given as:

ruleset_expr:
  rule_expr[|rule_expr ...]

rule_expr
  min,max,color

For example, suppose one wishes to define the following rules:

  • Where less than 100 records exist, use a transparent red (#FF000033)
  • Where 100-10000 records exist, use a transparent green (#00FF0033)
  • Where 10000 or more records exist, use a transparent blue (#0000FF33)

The resultant ruleset (before encoding would be):

,100,#FF000033|100,10000,#00FF0033|10000,,#0000FF33

The preview functionality allows you to test styles. A very useful resource providing color advice for cartographers is colorbrewer2.org.

Saturation and Hue

If you set &saturation to true then you can specify a &hue between 0.0 and 1.0 and achieve a very different effect when visualizing the GBIF data. These settings are what allow maps as seen on the occurrence homepage. It is a very different way of describing colour from what is described above - Wikipedia has a good introduction to Hue, Saturation, and Brightness.

Preview

Customise

Type

Key (or ISO country code)

Configured URL template (replace the {x},{y} and {z} accordingly):

  • Customize the layer

    Obs.

    Spe.

    Oth.

    No year

    1900-1910

    1910-1920

    1920-1930

    1930-1940

    1940-1950

    1950-1960

    1960-1970

    1970-1980

    1980-1990

    1990-2000

    2000-2010

    2010+

    Living

    Fossil

  • Customize the color