∿ Leypur Data API

API Docs

Current public endpoints exposed by the Leypur Data API web application. The API reads repository data from Leypur's Dataverse instance and returns map-ready metadata, Dataverse collection lists, and selected dataset PNG previews.

Health check

GET /health

Checks whether the web application can reach the configured Dataverse instance. This is mainly useful for deployment checks and debugging.

Example response

{
  "ok": true,
  "dataverse": {
    "status": "OK",
    "data": {
      "version": "6.9"
    }
  }
}

List Dataverse collections

GET /api/v1/dataverses

Returns the Dataverse collections discovered through the Dataverse search API. The map uses this endpoint to populate the collection filter.

Optional query parameters

?refresh=1

Forces the backend to rebuild the cached collection list instead of returning the currently cached response.

Authentication

The endpoint uses public Dataverse access by default. Private or restricted records can be included by sending a Dataverse API token with one of these headers: 

X-Dataverse-key: YOUR_TOKEN
Authorization: Bearer YOUR_TOKEN

Dataset map snapshot

GET /api/v1/sensors.geojson

Returns a GeoJSON FeatureCollection containing one point feature per dataset that has usable geospatial metadata. This is the main endpoint used by the dataset map.

Common examples

GET /api/v1/sensors.geojson
GET /api/v1/sensors.geojson?subtree=dv1
GET /api/v1/sensors.geojson?subtree=dv1,dv2
GET /api/v1/sensors.geojson?refresh=1
GET /api/v1/sensors.geojson?subtree=dv1&refresh=1

The subtree parameter limits the snapshot to one or more Dataverse collection aliases. The refresh=1 parameter forces the server to fetch a fresh snapshot from Dataverse.

Example response structure

{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "properties": {
        "id": "perma:DV/EXAMPLE",
        "name": "havstovan - NWZC1109",
        "url": "https://leypur.fo/...",
        "publisher": "havstovan",
        "description": "...",
        "dataverse_alias": "dv1",
        "dataverse_name": "Dataverse One",
        "file_count": 8,
        "has_files": true,
        "has_png_files": true,
        "png_file_count": 1,
        "data_types": ["adcp"],
        "data_type_labels": ["ADCP"],
        "keywords": ["ADCP"],
        "time_start": "2019-08-08",
        "time_end": "2019-10-10",
        "has_time_period": true,
        "west": -6.8,
        "east": -6.8,
        "north": 62.0,
        "south": 62.0,
        "has_bbox": true
      },
      "geometry": {
        "type": "Point",
        "coordinates": [-6.8, 62.0]
      }
    }
  ],
  "meta": {
    "filtering_mode": "client",
    "server_filters": ["subtree", "auth token", "refresh"],
    "client_filters": [
      "has_files",
      "has_png",
      "data_type",
      "time_period",
      "text_search",
      "selected_only"
    ]
  }
}

Important behaviour

The first request can take longer because the backend has to query Dataverse, inspect dataset metadata, check files, detect PNG previews, and extract geospatial and temporal fields. After that, most filtering is performed client-side in the browser using the returned snapshot.

Dataset PNG previews

GET /api/v1/datasets/images?persistentId=perma:DV/EXAMPLE

Returns PNG files attached to a selected Dataverse dataset. The dataset map uses this endpoint only after a dataset marker or result has been selected, instead of loading image previews for every dataset upfront.

Accepted query parameters

?persistentId=perma:DV/EXAMPLE
?persistent_id=perma:DV/EXAMPLE
?pid=perma:DV/EXAMPLE
?refresh=1

Example response

{
  "persistent_id": "perma:DV/EXAMPLE",
  "count": 1,
  "max_images": 12,
  "auth_used": false,
  "images": [
    {
      "id": 123,
      "filename": "windrose.png",
      "label": "windrose.png",
      "description": "",
      "content_type": "image/png",
      "filesize": 45231,
      "url": "https://leypur.fo/api/access/datafile/123",
      "original_url": "https://leypur.fo/api/access/datafile/123?format=original"
    }
  ],
  "truncated": false
}

Error response

{
  "error": "Missing required query parameter: persistentId"
}

Authentication model

The API uses public Dataverse access by default. For browser testing, the dataset map also supports an optional Dataverse API token. When a token is provided, the backend forwards it to Dataverse using the X-Dataverse-key header. 

X-Dataverse-key: YOUR_TOKEN
Authorization: Bearer YOUR_TOKEN

Token-specific responses are cached separately from public responses, so public and authenticated snapshots do not overwrite each other.

Caching and refresh behaviour

The web app caches expensive Dataverse lookups server-side to keep the map responsive. The returned map data should be treated as a snapshot, not a live feed. 

GET /api/v1/dataverses?refresh=1
GET /api/v1/sensors.geojson?refresh=1
GET /api/v1/datasets/images?persistentId=perma:DV/EXAMPLE&refresh=1

Use refresh=1 when you need the newest Dataverse updates. Otherwise, filters such as collection, data type, PNG presence, file presence, time period, and text search can be applied instantly in the browser from the existing snapshot.

Currently not implemented

The following earlier planned endpoints are not currently exposed by the Flask app and should not be documented as available unless they are implemented later: 

GET /api/v1/datasets
GET /api/v1/datasets/{id}/metadata
GET /api/v1/datasets/{id}/tracks.geojson
GET /api/v1/datasets/{id}/vectors.geojson