Skip to content

GeoBTAA API Specification

DRAFT Specification / Work in Progress

This portion of the BTAA GIN site, our GeoBTAA API, and our Linked Data offerings are a WORK IN PROGRESS. Please reach out if you have questions or wish to participate in bringing these resources to public release.

Version: 0.1.1-pre-alpha Status: DRAFT Release Date: 2025‑08‑22

Editors

  • Eric Larson, Big Ten Academic Alliance
  • Karen Majewicz, Big Ten Academic Alliance

Copyright © 2025 Editors and Contributors. Published by BTAA GIN under the CC-BY license, see disclaimer.

Introduction

The GeoBTAA API is an OpenGeoMetadata API-compliant, read‑only, web service for programmatically accessing, searching, and retrieving metadata records that conform to the BTAA GIN’s GeoBTAA extended-OGM Aardvark schema (opengeometadata.org + https://gin.btaa.org/metadata/b1g-custom-elements). The API is designed to be an efficient backend, powering search and geospatial discovery, for any frontend technology.

In addition to structured metadata retrieval, the API can drive user interface components — such as field hints, thumbnails, citations, and viewer configurations — that support search, web service previews, and other interactive features within geospatial discovery applications.

This specification deliberately echoes the style and structure of the IIIF specifications (iiif.io), providing:

  • A small, RESTful surface area with predictable, cache‑friendly URLs
  • Explicit parameter semantics
  • Normative requirements using MUST, SHOULD, MAY as defined by RFC 2119

The goal of this specification is to enable consistent client and server implementations across the OGM community.

Scope

  • In scope – Retrieval of individual resources, list endpoints, full‑text and spatial search, simple authentication, usage limits.
  • Out of scope – Write operations (create/update/delete), bulk harvesting, or authentication flows beyond API keys (e.g. OAuth 2).

Audience

  • BTAA GIN Member Libraries
  • Client developers (e.g. FastAPI-based geoportals, desktop GIS plugins)
  • Researchers automating metadata discovery

Change Log

Version Date Notes
0.1.1-pre-alpha 2025‑08‑22 Broad revisions.
0.1.0-pre-alpha 2025‑07‑22 Initial draft.

Acknowledgements

This specification borrows heavily from the structure and editorial approach of the IIIF community (iiif.io) and benefits from prior work by the GeoBlacklight and OpenGeoMetadata communities.