How it works

This version of our Geospatial RESTful web service is conceived to be used in machine-to-machine data transfers by the means of HTTPS POST calls executed by a User’s client app or script, submitting request parameters as a JSON object in the request body, and receiving information still in JSON format.

After an initial registration and email confirmation, Users can call the web service by submitting their credentials along with any service call. The HTTPS channel ensures the confidentiality of Users’ credentials.

For non-technical audience: please note web services are not web applications, hence apart from this guide explaining its functions, a user’s interface allowing to interact with the service cannot be put in place. For the usage of this web service, like any other web service, please use common applications available for download, e.g. Telerik Fiddler, or code your own script (e.g. through Curl) or custom applications. The intended audience of this guide is technicians understanding the web, the http/s protocol, the REST paradigm, scripting and coding capabilities.

User’s registration

Step One

Step Two

The User is to click on the received link in order to confirm the existence of its email address. A basic message is displayed in the User’s web browser saying the email is now confirmed and the web service usage can start.

Please note: Users having an EU-Login account must use an email account other than the one used in EU-Login.

Getting species occurrences

To retrieve and get species occurrences, the User client has to POST a call to https://easin.jrc.ec.europa.eu/apixg2/geo/getoccurrences still having a JSON MIME Type entry in the request header.

The request body must contain a JSON object formed like the following:

{
    "Email": "youremail@yourdomain",
    "Password": "yourpassword",
    "speciesId": "[EASIN Species ID] or 'ALL'",
    "countryCode": "A country code or an empty string",
    "dataPartners": "comma separated list of Data Partners ID",
    "excludePartners": 0 or 1,
    "skip": number of record to skip (the offset),
    "take": number or record to take (the fetch)
}

• speciesId: if retrieving occurrences of a specific specie, please pass the EASIN Species ID of your interest. You can obtain the EASIN Species ID by different means:
  • The EASIN Species mapper, search for species and expand the search result to see species information.
  • The EASIN Species Factsheets >> [Species Factsheet] submenu Item, and search for a single species by name.
  • Get a full list of species in the EASIN Catalogue by using the EASIN Catalogue Web service.
    In particular the endpoint at https://easin.jrc.ec.europa.eu/apixg/catxg/getall/skip/0/take/15000 retrieves the full catalogue basic information in a single call.
• Country code: users have to pass a specific Country code to retrieve species occurrences in a specific Country, or pass an empty string for occurrences in any Country.
  Users may also pass a comma separated list of country codes in order to retrieve occurrences in more than one country e.g. "AT,BE,BG".
  Here is the full list of Country codes used in EASIN:
  • "AT" = Austria
  • "BE" = Belgium
  • "BG" = Bulgaria
  • "HR" = Croatia
  • "CY" = Cyprus
  • "CZ" = Czechia
  • "DK" = Denmark
  • "EE" = Estonia
  • "FI" = Finland
  • "FR" = France
  • "DE" = Germany
  • "EL" = Greece
  • "HU" = Hungary
  • "IE" = Ireland
  • "IT" = It
  • "LV" = Latvia
  • "LT" = Lithuania
  • "LU" = Luxembourg
  • "MT" = Malta
  • "NL" = Netherlands
  • "PL" = Poland
  • "PT" = Portugal
  • "RO" = Romania
  • "SK" = Slovakia
  • "SI" = Slovenia
  • "ES" = Spain
  • "SE" = Sweden
  • "XI" = UK in respect of Northern Ireland
• Data partners: please pass a comma separated data partners id within a string.
  Example "dataPartners": "1,2,3,4,5,6,7,8".
  To get a full list of data partners along with their numerical IDs, please make a GET call to https://easin.jrc.ec.europa.eu/apixg/geoxg/datapartners (even by a web browser).
• Skip and take: based on the capabilities of Users’ clients/hardware in handling high numbers of output JSON objects, the service output can be obtained in shorter or longer subsequent trunks.
  E.g. by passing the following JSON paramaters the user will get the ‘first’ five hundred JSON objects, while passing skip = 500 and take = 500, the subsequent five hundred JSON objects are extracted and exposed by the service.

  {
      …
      “skip”: 0,
      “take”: 500
  }