Presentation

1. Introduction

What is the BTAA Geoportal API?

The API powers the BTAA Geoportal frontend and provides external access to our digital collection of geospatial resources. It allows for automation, integration into GIS software (like QGIS), and bulk data analysis.

Core Concepts

RESTful Design: Standard HTTP methods (GET).
JSON:API Standard: Responses are structured with data, attributes, meta, and links.
Base URL: https://lib-btaageoapi-dev-app-01.oit.umn.edu/api/v1/

2. The Search Endpoint

The primary entry point for discovery is /search.

Key Parameters

q: The main keyword search parameter (e.g., ?q=seattle).
include_filters: Target specific fields (e.g., include_filters[gbl_resourceClass_sm][]=Maps).
page & per_page: Control pagination.
sort: Order results (e.g., year_asc, relevance).

3. Anatomy of a Response

The API follows the JSON:API specification. Here is a breakdown of the key top-level sections you will see in a search response:

jsonapi

This object describes the version of the JSON:API specification the server implements. It ensures clients know how to parse the document structure reliably.

links

These are your navigation aids. They provide pre-built URLs for:

self: The current request.
next / prev: Pagination links to traverse the result set.
first / last: Jumping to the beginning or end of results.

data

The core array of resource objects. Each item contains:

attributes: The metadata record following the OpenGeoMetadata Aardvark schema.
meta: Additional UI helpers, such as thumbnail URLs and generated citations.

included

This section contains "side-loaded" data. In our search context, this is where facets and aggregations live (e.g., counts of maps by provider or year).

4. The Resource Endpoint

To get full details on a single item, use /resources/{id}.

Anatomy of a Resource

{
  "data": {
    "type": "resource",
    "id": "p16022coll205:660",
    "attributes": {
      "dct_title_s": "Guide map of Seattle",
      "dct_issued_s": "1924",
      "locn_geometry": "POLYGON((-122...))",
      "dct_references_s": "{...}" 
    }
  }
}

Tip: The dct_references_s attribute contains critical links to downloads and IIIF manifests.

5. Practical Application

We have prepared 11 practical "recipes" or examples to demonstrate common tasks, from basic searching to extracting IIIF manifests for map viewers.

View Code Examples