Endpoints

packages = ["requests", "pyodide-http"]

DRAFT Specification / Work in Progress

This portion of the BTAA GIN site, our BTAA Geospatial 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.

API Swagger Documentation

Production Server

https://geo.btaa.org/api/docs

Endpoint Index

The tables below enumerate all current non-admin endpoints exposed by the API.

Root

Method	Path	Notes
GET	/api/v1/	API root

Search

Method	Path	Notes
GET	/api/v1/search	Search resources (query params)
POST	/api/v1/search	Search resources (JSON body)
GET	/api/v1/search/facets/{facet_name}	Paginated facet values
GET	/api/v1/suggest	Autosuggestions

Resources

Method	Path	Notes
GET	/api/v1/resources/	List resources
GET	/api/v1/resources/{id}	Get one resource
GET	/api/v1/resources/{id}/citation	Citation payload
GET	/api/v1/resources/{id}/citation/json-ld	Citation as JSON-LD
GET	/api/v1/resources/{id}/citation/ris	Citation in RIS format
GET	/api/v1/resources/{id}/citation/bibtex	Citation in BibTeX format
GET	/api/v1/resources/{id}/data-dictionaries	Resource data dictionary entries
GET	/api/v1/resources/{id}/distributions	Resource distributions
GET	/api/v1/resources/{id}/downloads	Download links and metadata
GET	/api/v1/resources/{id}/downloads/generated/{download_type}	Prepare generated download and return file URL
GET	/api/v1/resources/{id}/downloads/generated/{download_type}/file	Download generated file attachment
GET	/api/v1/resources/{id}/links	Resource links
GET	/api/v1/resources/{id}/metadata	Combined metadata
GET	/api/v1/resources/{id}/metadata/ogm	OGM-transformed metadata
GET	/api/v1/resources/{id}/metadata/b1g	B1G metadata format
GET	/api/v1/resources/{id}/metadata/display	HTML metadata display
GET	/api/v1/resources/{id}/ogm-viewer	OGM viewer payload
GET	/api/v1/resources/{id}/relationships	Related resources
GET	/api/v1/resources/{id}/similar-items	Similar resources
GET	/api/v1/resources/{id}/spatial-facets	Spatial facet values
GET	/api/v1/resources/{id}/static-map	Cached static map image
GET	/api/v1/resources/{id}/static-map/no-cache	Uncached static map image
GET	/api/v1/resources/{id}/thumbnail	Cached thumbnail image
GET	/api/v1/resources/{id}/thumbnail/no-cache	Uncached thumbnail image
GET	/api/v1/resources/{id}/viewer	Viewer configuration payload

Maps and Thumbnails

Method	Path	Notes
GET	/api/v1/map/h3	H3 map tile/geometry data
GET	/api/v1/static-maps/institutions/{map_id}	Institution static map
GET	/api/v1/static-map-assets/{map_hash}	Generated static-map asset by hash
GET	/api/v1/static-maps/{resource_id}/geometry	Resource geometry for static-map rendering
GET	/api/v1/static-maps/{resource_id}/resource-class-icon	Resource-class icon used by static-map rendering
GET	/api/v1/static-maps/{resource_id}	Resource static map
GET	/api/v1/thumbnails/placeholder	Placeholder thumbnail
GET	/api/v1/thumbnails/{resource_id}	Thumbnail by resource ID

OGM and Harvest Status

Method	Path	Notes
GET	/api/v1/ogm/repos	Enabled/known OGM repositories
GET	/api/v1/ogm/harvest/failures	OGM harvest failure summary

OGC API

Method	Path	Notes
GET	/api/v1/ogc/	OGC API landing page
GET	/api/v1/ogc/conformance	OGC conformance classes
GET	/api/v1/ogc/collections	Collections listing
GET	/api/v1/ogc/collections/btaa-records	BTAA records collection
GET	/api/v1/ogc/collections/btaa-records/queryables	Queryable fields
GET	/api/v1/ogc/collections/btaa-records/sortables	Sortable fields
GET	/api/v1/ogc/collections/btaa-records/items	Collection items
GET	/api/v1/ogc/collections/btaa-records/items/{recordId}	Single OGC record

Model Context Protocol (MCP)

Method	Path	Notes
GET	/api/v1/mcp	Model Context Protocol endpoint
POST	/api/v1/mcp	Streamable HTTP MCP transport

Root Endpoint

Provides a basic service-level entrypoint for API discovery.

Method	Path	Notes
GET	/api/v1/	API root response

Interactive Example: API Root

API Root

Root

Goal: Check the API root response.

Request: GET /api/v1/

Python API Response Output

Copy

import requests
import json

API_ROOT_EXAMPLE_URL = "https://geo.btaa.org/api/v1/"

response = requests.get(API_ROOT_EXAMPLE_URL)
data = response.json()

print(f"Status: {response.status_code}")
print("Top-level keys:", list(data.keys()))

Copy

Click "Run" to see the API response...

Copy

Click "Run" to see the output...

Run Example

Response notes

• Returns a lightweight JSON payload suitable for liveness and API entrypoint checks.
• Useful for quickly validating API availability before issuing search/resource requests.

Search Endpoint

Supports both GET (simple) and POST (complex) forms.

Method	Path	Notes
GET or POST	/search	Returns a JSON:API resultset of Resources

Interactive Example: Simple Search

Simple Search

Search

Goal: Find all resources related to "water".

Request: GET /api/v1/search?q=water

Python API Response Output

📋 Copy

import requests
import json

BASE_URL = "https://geo.btaa.org/api/v1"

# Step 1: Text search for 'water'
params = {
    'q': 'water',
    'page': 1,
    'per_page': 10
}

response = requests.get(f"{BASE_URL}/search", params=params)
data = response.json()

print(f"Total number of resources found: {data.get('meta', {}).get('totalCount')}")

print("\nList of titles:")
for item in data.get('data', []):
    print(f"  - {item['attributes'].get('dct_title_s', 'N/A')}")

📋 Copy

Click "Run" to see the API response...

📋 Copy

Click "Run" to see the output...

▶ Run Example

Search Examples

Field-Directed Search

Field-Directed Search

Advanced Search

Goal: Search for "Transportation" specifically in the Subject field.

Request: GET /api/v1/search?q=Transportation&search_field=dct_subject_sm

Python API Response Output

📋 Copy

import requests
import json

BASE_URL = "https://geo.btaa.org/api/v1"

# Step 4: Field-directed search
params = {
    'q': 'Transportation',
    'search_field': 'dct_subject_sm',
    'page': 1,
    'per_page': 10
}

response = requests.get(f"{BASE_URL}/search", params=params)
data = response.json()

print(f"Total number of resources found: {data.get('meta', {}).get('totalCount')}")

print("\nList of titles:")
for item in data.get('data', []):
    print(f"  - {item['attributes'].get('dct_title_s', 'N/A')}")

📋 Copy

Click "Run" to see the API response...

📋 Copy

Click "Run" to see the output...

▶ Run Example

Boolean Search

Boolean Search

Advanced Search

Goal: Search for "(water AND ice) NOT Forest".

Request: GET /api/v1/search?q=(water AND ice) NOT Forest

Python API Response Output

📋 Copy

import requests
import json

BASE_URL = "https://geo.btaa.org/api/v1"

# Step 3: Boolean search
params = {
    'q': '(water AND ice) NOT Forest',
    'page': 1,
    'per_page': 10
}

response = requests.get(f"{BASE_URL}/search", params=params)
data = response.json()

print(f"Total number of resources found: {data.get('meta', {}).get('totalCount')}")

print("\nList of titles:")
for item in data.get('data', []):
    print(f"  - {item['attributes'].get('dct_title_s', 'N/A')}")

📋 Copy

Click "Run" to see the API response...

📋 Copy

Click "Run" to see the output...

▶ Run Example

Faceted Search — Includes

Faceted Search (Includes)

Facets

Goal: Search for "seattle", filter for "Maps" AND "Washington".

Request: GET /api/v1/search?q=seattle&include_filters...

Python API Response Output

📋 Copy

import requests
import json

BASE_URL = "https://geo.btaa.org/api/v1"

# Step 6: Faceted search (Maps + Washington)
params = {
    'q': 'seattle',
    'include_filters[gbl_resourceClass_sm][]': 'Maps',
    'include_filters[dct_spatial_sm][]': 'Washington',
    'page': 1,
    'per_page': 10
}

response = requests.get(f"{BASE_URL}/search", params=params)
data = response.json()

print(f"Total Found: {data.get('meta', {}).get('totalCount')}")

print("\nList of titles:")
for item in data.get('data', []):
    print(f"  - {item['attributes'].get('dct_title_s', 'N/A')}")

📋 Copy

Click "Run" to see the API response...

📋 Copy

Click "Run" to see the output...

▶ Run Example

Faceted Search — Excludes

Faceted Search (Excludes)

Facets

Goal: Search for "seattle", filter for "Maps", "Washington", but EXCLUDE "Pennsylvania State University".

Request: GET /api/v1/search?q=seattle&exclude_filters...

Python API Response Output

📋 Copy

import requests
import json

BASE_URL = "https://geo.btaa.org/api/v1"

# Step 7: Faceted search (Maps + Washington - PSU)
params = {
    'q': 'seattle',
    'include_filters[gbl_resourceClass_sm][]': 'Maps',
    'include_filters[dct_spatial_sm][]': 'Washington',
    'exclude_filters[schema_provider_s][]': 'Pennsylvania State University',
    'page': 1,
    'per_page': 10
}

response = requests.get(f"{BASE_URL}/search", params=params)
data = response.json()

print(f"Total Found: {data.get('meta', {}).get('totalCount')}")

print("\nList of titles:")
for item in data.get('data', []):
    print(f"  - {item['attributes'].get('dct_title_s', 'N/A')}")

📋 Copy

Click "Run" to see the API response...

📋 Copy

Click "Run" to see the output...

▶ Run Example

Spatial Search — BBox

Spatial Search (BBox)

Spatial

Goal: Compare BBox search with within and overlap spatial modes.

Request: GET /api/v1/search?q=maps&include_filters[geo][type]=bbox&include_filters[geo][relation]=within|overlap...

Python API Response Output

📋 Copy

import requests
import json

BASE_URL = "https://geo.btaa.org/api/v1"

# Step 8a: Bounding Box Search (Minnesota) - within
within_params = {
    'q': 'maps',
    'include_filters[geo][type]': 'bbox',
    'include_filters[geo][field]': 'dcat_bbox',
    'include_filters[geo][relation]': 'within',
    'include_filters[geo][top_left][lat]': '49.0',
    'include_filters[geo][top_left][lon]': '-97.2',
    'include_filters[geo][bottom_right][lat]': '43.5',
    'include_filters[geo][bottom_right][lon]': '-89.5',
    'page': 1,
    'per_page': 10
}
within_response = requests.get(f"{BASE_URL}/search", params=within_params)
within_data = within_response.json()

# Step 8b: Bounding Box Search (Minnesota) - overlap
overlap_params = dict(within_params)
overlap_params['include_filters[geo][relation]'] = 'overlap'
overlap_response = requests.get(f"{BASE_URL}/search", params=overlap_params)
overlap_data = overlap_response.json()

print(f"within total: {within_data.get('meta', {}).get('totalCount')}")
print(f"overlap total: {overlap_data.get('meta', {}).get('totalCount')}")

📋 Copy

Click "Run" to see the API response...

📋 Copy

Click "Run" to see the output...

▶ Run Example

Spatial Search — Distance

Spatial Search (Distance)

Spatial

Goal: Find "parks" resources within 50km of Minneapolis.

Request: GET /api/v1/search?q=parks&include_filters[geo][type]=distance...

Python API Response Output

📋 Copy

import requests
import json

BASE_URL = "https://geo.btaa.org/api/v1"

# Step 9: Distance Search (50km from Minneapolis)
params = {
    'q': 'parks',
    'include_filters[geo][type]': 'distance',
    'include_filters[geo][field]': 'dcat_centroid',
    'include_filters[geo][center][lat]': '44.9778',
    'include_filters[geo][center][lon]': '-93.2650',
    'include_filters[geo][distance]': '50km',
    'page': 1,
    'per_page': 10
}

response = requests.get(f"{BASE_URL}/search", params=params)
data = response.json()

print(f"Total Found: {data.get('meta', {}).get('totalCount')}")

print("\nList of titles:")
for item in data.get('data', []):
    print(f"  - {item['attributes'].get('dct_title_s', 'N/A')}")

📋 Copy

Click "Run" to see the API response...

📋 Copy

Click "Run" to see the output...

▶ Run Example

Spatial Search — Polygon

Spatial Search (Polygon)

Spatial

Goal: Find "water" resources intersecting with Colorado state boundaries.

Request: GET /api/v1/search?q=water&include_filters[geo][type]=polygon...

Python API Response Output

📋 Copy

import requests
import json

BASE_URL = "https://geo.btaa.org/api/v1"

# Step 10: Polygon Search (Colorado)
params = {
    'q': 'water',
    'include_filters[geo][type]': 'polygon',
    'include_filters[geo][field]': 'locn_geometry',
    'include_filters[geo][relation]': 'intersects',
    'include_filters[geo][points][0][lat]': '41.0',
    'include_filters[geo][points][0][lon]': '-109.0',
    'include_filters[geo][points][1][lat]': '41.0',
    'include_filters[geo][points][1][lon]': '-102.0',
    'include_filters[geo][points][2][lat]': '37.0',
    'include_filters[geo][points][2][lon]': '-102.0',
    'include_filters[geo][points][3][lat]': '37.0',
    'include_filters[geo][points][3][lon]': '-109.0',
    'page': 1,
    'per_page': 10
}

response = requests.get(f"{BASE_URL}/search", params=params)
data = response.json()

print(f"Total Found: {data.get('meta', {}).get('totalCount')}")

print("\nList of titles:")
for item in data.get('data', []):
    print(f"  - {item['attributes'].get('dct_title_s', 'N/A')}")

📋 Copy

Click "Run" to see the API response...

📋 Copy

Click "Run" to see the output...

▶ Run Example

Advanced Search

Advanced Search (adv_q)

Advanced

Goal: Find "Maps" having "Island" in title but NOT "Antarctica".

Request: GET /api/v1/search?q=&adv_q=...

Python API Response Output

📋 Copy

import requests
import json

BASE_URL = "https://geo.btaa.org/api/v1"

# Step 11: Advanced Search with adv_q
# Logic: (ResourceClass=Maps AND Title=Island) NOT Title=Antarctica
adv_query = [
    {"op": "AND", "f": "gbl_resourceClass_sm", "q": "Maps"},
    {"op": "AND", "f": "dct_title_s", "q": "Island"},
    {"op": "NOT", "f": "dct_title_s", "q": "antarctica"}
]

params = {
    'q': '',
    'adv_q': json.dumps(adv_query),
    'page': 1,
    'per_page': 10
}

response = requests.get(f"{BASE_URL}/search", params=params)
data = response.json()

print(f"Total Found: {data.get('meta', {}).get('totalCount')}")

print("\nList of titles:")
for item in data.get('data', []):
    print(f"  - {item['attributes'].get('dct_title_s', 'N/A')}")

📋 Copy

Click "Run" to see the API response...

📋 Copy

Click "Run" to see the output...

▶ Run Example

Search Parameters

Parameter	Type	Description
q	string	Full‑text query (default *:*).
fq	object	Active facet include filters (same as include_filters)
search_field	string (CSV)	Search field (all_fields [default], etc.)
page	integer	Current page of results
per_page	integer	Number of results to return
sort	string	Sort option (relevance, year_desc, year_asc, title_asc, title_desc)
format	string	Format option (JSON [default], JSONP)
callback	string	JSONP callback name
fields	string (CSV)	List of fields to return
facets	string (CSV)	List of facets to return
include_filters	object	Active facet include filters (same as fq)
exclude_filters	object	Active facet exclude filters
meta	boolean	Include META (default true)
adv_q	string	JSON array of advanced query clauses. Example: {'op': 'AND|OR|NOT', 'f': 'dct_title_s', 'q': 'Iowa'}
include_non_public	boolean	Include unpublished and suppressed records; default searches require publication_state=published and gbl_suppressed_b=false

Search Facet Pagination

Method	Path	Notes
GET	/search/facets/{facet_name}	Get paginated, sortable facet values for a specific facet field within a search resultset.

Interactive Example: Search Facet Pagination

Facet Pagination

Search

Goal: Get paginated facet values for the resource class facet.

Request: GET /api/v1/search/facets/gbl_resourceClass_sm

Python API Response Output

📋 Copy

import requests
import json

BASE_URL = "https://geo.btaa.org/api/v1"

# Get paginated facet values for resource class
facet_name = "gbl_resourceClass_sm"
params = {
    'page': 1,
    'per_page': 10,
    'sort': 'count_desc'
}

response = requests.get(f"{BASE_URL}/search/facets/{facet_name}", params=params)
data = response.json()

print(f"Facet: {facet_name}")
print(f"Total values: {data.get('meta', {}).get('totalCount', 0)}")
print(f"Page: {data.get('meta', {}).get('currentPage', 1)}")
print(f"Per page: {data.get('meta', {}).get('perPage', 10)}")

for item in data.get('data', []):
    attrs = item.get('attributes', {})
    value = attrs.get('value', 'N/A')
    count = attrs.get('hits', 0)
    print(f"  {value}: {count}")

📋 Copy

Click "Run" to see the API response...

📋 Copy

Click "Run" to see the output...

▶ Run Example

Parameters

Name	Type	Req?	Description
facet_name	string	✔️	Facet field name (e.g., gbl_resourceClass_sm)
q	string		Search query to filter resultset
page	integer		Page number (minimum: 1, default: 1)
per_page	integer		Facet values per page (1-100, default: 10)
sort	string		Sort option: count_desc, count_asc, alpha_asc, alpha_desc (default: count_desc)
q_facet	string		Search query to filter facet values
adv_q	string		JSON array of advanced query clauses. Each clause: {'op': 'AND\|OR\|NOT', 'f': 'dct_title_s', 'q': 'Iowa'}
include_non_public	boolean		Include unpublished and suppressed records

Search Autosuggestions

Method	Path	Notes
GET	/suggest	Get search suggestions.

Interactive Example: Search Autosuggestions

Search Autosuggestions

Search

Goal: Get search suggestions for "Minn".

Request: GET /api/v1/suggest?q=Minn

Python API Response Output

📋 Copy

import requests
import json

BASE_URL = "https://geo.btaa.org/api/v1"

# Get search suggestions
params = {
    'q': 'Minn'
}

response = requests.get(f"{BASE_URL}/suggest", params=params)
data = response.json()

print(f"Suggestions for 'Minn':")
for suggestion in data.get('suggestions', []):
    print(f"  - {suggestion}")

📋 Copy

Click "Run" to see the API response...

📋 Copy

Click "Run" to see the output...

▶ Run Example

Parameters

Name	Type	Req?	Description
q	string	✔️	Search query for suggestions
callback	string		JSONP callback name
include_non_public	boolean		Include unpublished and suppressed records

Resource Endpoint

Method	Path	Notes
GET	/resources/{id}	Returns a single Aardvark record, wrapped in JSON:API frontmatter.

Interactive Example: Obtain a Resource

Obtain a Resource

Resource

Goal: Fetch metadata for a specific resource ID.

Request: GET /api/v1/resources/ark28722-s7vs38

Python API Response Output

📋 Copy

import requests
import json

BASE_URL = "https://geo.btaa.org/api/v1"

# Step 2: Fetch a specific resource
resource_id = "ark28722-s7vs38"
response = requests.get(f"{BASE_URL}/resources/{resource_id}")
data = response.json()

attrs = data['data']['attributes']
print(f"Title: {attrs.get('dct_title_s', 'N/A')}")
print(f"Description: {attrs.get('dct_description_sm', ['N/A'])[0]}")

# Show references
if 'dct_references_s' in attrs:
    refs = json.loads(attrs['dct_references_s'])
    for key, value in refs.items():
        print(f"{key}: {value}")

📋 Copy

Click "Run" to see the API response...

📋 Copy

Click "Run" to see the output...

▶ Run Example

Parameters

Name	Type	Req?	Description
id	string	✔️	Canonical record ID
fields	string (CSV)		Subset of fields to include

Resource Helper Endpoints

List Resources

List Resources

Resource

Goal: Get a list of Aardvark records.

Request: GET /api/v1/resources/

Python API Response Output

📋 Copy

import requests
import json

BASE_URL = "https://geo.btaa.org/api/v1"

# List resources
response = requests.get(f"{BASE_URL}/resources/")
data = response.json()

print(f"Total resources: {data.get('meta', {}).get('totalCount', 0)}")
print(f"Page: {data.get('meta', {}).get('currentPage', 1)}")
print(f"Per page: {data.get('meta', {}).get('perPage', 10)}")

# Show first few resources
for item in data.get('data', [])[:5]:
    attrs = item.get('attributes', {})
    ogm = attrs.get('ogm', {})
    print(f"\nID: {item.get('id')}")
    print(f"Title: {ogm.get('dct_title_s', attrs.get('dct_title_s', 'N/A'))}")

📋 Copy

Click "Run" to see the API response...

📋 Copy

Click "Run" to see the output...

▶ Run Example

Resource — Citation

Resource Citation

Resource

Goal: Get citation information for a resource.

Request: GET /api/v1/resources/{id}/citation

Python API Response Output

📋 Copy

import requests
import json

BASE_URL = "https://geo.btaa.org/api/v1"

# Get citation for a resource
resource_id = "ark28722-s7vs38"
response = requests.get(f"{BASE_URL}/resources/{resource_id}/citation")
data = response.json()

print(f"Citation for resource: {resource_id}")
print(f"Citation: {data.get('citation', 'N/A')}")

📋 Copy

Click "Run" to see the API response...

📋 Copy

Click "Run" to see the output...

▶ Run Example

Resource — Distributions

Resource Distributions

Resource

Goal: Get distribution information for a resource.

Request: GET /api/v1/resources/{id}/distributions

Python API Response Output

📋 Copy

import requests
import json

BASE_URL = "https://geo.btaa.org/api/v1"

# Get distributions for a resource
resource_id = "ark28722-s7vs38"
response = requests.get(f"{BASE_URL}/resources/{resource_id}/distributions")
data = response.json()

print(f"Distributions for resource: {resource_id}")
for dist in data.get('distributions', []):
    print(f"Type: {dist.get('distribution_type', dist.get('distribution_type_name', 'N/A'))}")
    print(f"URL: {dist.get('url', 'N/A')}")

📋 Copy

Click "Run" to see the API response...

📋 Copy

Click "Run" to see the output...

▶ Run Example

Resource — Downloads

Resource Downloads

Resource

Goal: Get download information for a resource.

Request: GET /api/v1/resources/{id}/downloads

Python API Response Output

📋 Copy

import requests
import json

BASE_URL = "https://geo.btaa.org/api/v1"

# Get downloads for a resource
resource_id = "ark28722-s7vs38"
response = requests.get(f"{BASE_URL}/resources/{resource_id}/downloads")
data = response.json()

print(f"Downloads for resource: {resource_id}")
for download in data.get('downloads', []):
    print(f"Label: {download.get('label', 'N/A')}")
    print(f"Type: {download.get('type', 'N/A')}")
    print(f"Format: {download.get('format', 'N/A')}")
    print(f"URL: {download.get('url', 'N/A')}")

📋 Copy

Click "Run" to see the API response...

📋 Copy

Click "Run" to see the output...

▶ Run Example

Generated Download Workflow

The downloads payload may include generated exports with:

• generated: true
• download_type (for example: shapefile, geojson, csv, kmz, geotiff)
• generation_path (API path for preparing the file)

Generated downloads use a two-step flow:

1. Call GET /api/v1/resources/{id}/downloads/generated/{download_type} to prepare (or reuse) the generated artifact.
2. Use the returned download_url (or call /file directly) to download the attachment.

Method	Path	Notes
GET	/api/v1/resources/{id}/downloads/generated/{download_type}	Prepares and returns JSON metadata for the generated artifact
GET	/api/v1/resources/{id}/downloads/generated/{download_type}/file	Returns file attachment bytes (Content-Disposition: attachment)

Supported download_type values

• shapefile (EPSG:4326 Shapefile)
• geojson
• csv
• kmz
• geotiff

Prepare example

curl "https://geo.btaa.org/api/v1/resources/stanford-bs024ty5255/downloads/generated/geojson"

Example response:

{
  "download_type": "geojson",
  "file_name": "stanford-bs024ty5255-geojson.geojson",
  "file_path": "/app/tmp/cache/downloads/stanford-bs024ty5255-geojson.geojson",
  "content_type": "application/json",
  "download_url": "/api/v1/resources/stanford-bs024ty5255/downloads/generated/geojson/file"
}

File download example

curl -L -OJ "https://geo.btaa.org/api/v1/resources/stanford-bs024ty5255/downloads/generated/geojson/file"

Resource — Links

Resource Links

Resource

Goal: Get link information for a resource.

Request: GET /api/v1/resources/{id}/links

Python API Response Output

📋 Copy

import requests
import json

BASE_URL = "https://geo.btaa.org/api/v1"

# Get links for a resource
resource_id = "ark28722-s7vs38"
response = requests.get(f"{BASE_URL}/resources/{resource_id}/links")
data = response.json()

print(f"Links for resource: {resource_id}")
for category, links in data.items():
    print(f"\n{category}:")
    for link in links:
        print(f"  Label: {link.get('label', 'N/A')}")
        print(f"  URL: {link.get('url', 'N/A')}")

📋 Copy

Click "Run" to see the API response...

📋 Copy

Click "Run" to see the output...

▶ Run Example

Resource — Metadata Retrieval

Resource Metadata Retrieval

Resource

Goal: Get raw Aardvark metadata for a resource.

Request: GET /api/v1/resources/{id}/metadata

Python API Response Output

📋 Copy

import requests
import json

BASE_URL = "https://geo.btaa.org/api/v1"

# Get raw metadata for a resource
resource_id = "ark28722-s7vs38"
response = requests.get(f"{BASE_URL}/resources/{resource_id}/metadata")
data = response.json()

print(f"Raw metadata for resource: {resource_id}")
ogm = data.get('ogm', {})
print(f"Title: {ogm.get('dct_title_s', 'N/A')}")
desc = ogm.get('dct_description_sm', [])
print(f"Description: {desc[0] if isinstance(desc, list) and desc else 'N/A'}")

📋 Copy

Click "Run" to see the API response...

📋 Copy

Click "Run" to see the output...

▶ Run Example

Resource — OGM Viewer Retrieval

Resource OGM Viewer Retrieval

Resource

Goal: Get the Aardvark record as HTML presented in the OGM Viewer.

Request: GET /api/v1/resources/{id}/ogm-viewer

Python HTML Response Output

📋 Copy

import requests

BASE_URL = "https://geo.btaa.org/api/v1"

# Get OGM Viewer HTML for a resource
resource_id = "ark28722-s7vs38"
response = requests.get(f"{BASE_URL}/resources/{resource_id}/ogm-viewer")

if response.status_code == 200:
    html_content = response.text
    print(f"✅ OGM Viewer HTML for resource: {resource_id}")
    print(f"Content-Type: {response.headers.get('Content-Type', 'N/A')}")
    print(f"HTML length: {len(html_content)} characters")
    print(f"\nFirst 500 characters of HTML:")
    print(html_content[:500])
else:
    print(f"❌ Error: {response.status_code}")

📋 Copy

Click "Run" to see the HTML response...

📋 Copy

Click "Run" to see the output...

▶ Run Example

Resource — Relationships

Resource Relationships

Resource

Goal: Get relationship information for a resource.

Request: GET /api/v1/resources/{id}/relationships

Python API Response Output

📋 Copy

import requests
import json

BASE_URL = "https://geo.btaa.org/api/v1"

# Get relationships for a resource
resource_id = "ark28722-s7vs38"
response = requests.get(f"{BASE_URL}/resources/{resource_id}/relationships")
data = response.json()

print(f"Relationships for resource: {resource_id}")
for rel in data.get('data', []):
    attrs = rel.get('attributes', {})
    print(f"Type: {attrs.get('relationship_type', 'N/A')}")
    print(f"Related ID: {attrs.get('related_resource_id', 'N/A')}")

📋 Copy

Click "Run" to see the API response...

📋 Copy

Click "Run" to see the output...

▶ Run Example

Resource — Similar Items

Resource Similar Items

Resource

Goal: Get similar items for a resource.

Request: GET /api/v1/resources/{id}/similar-items

Python API Response Output

📋 Copy

import requests
import json

BASE_URL = "https://geo.btaa.org/api/v1"

# Get similar items for a resource
resource_id = "ark28722-s7vs38"
response = requests.get(f"{BASE_URL}/resources/{resource_id}/similar-items")
data = response.json()

print(f"Similar items for resource: {resource_id}")
for item in data.get('similar_items', [])[:5]:
    print(f"ID: {item.get('id', 'N/A')}")
    print(f"Title: {item.get('title', 'N/A')}")
    temporal = item.get('temporal_coverage', [])
    if temporal:
        print(f"Temporal Coverage: {', '.join(temporal)}")

📋 Copy

Click "Run" to see the API response...

📋 Copy

Click "Run" to see the output...

▶ Run Example

Resource — Spatial Facets

Resource Spatial Facets

Resource

Goal: Get spatial facet information for a resource.

Request: GET /api/v1/resources/{id}/spatial-facets

Python API Response Output

📋 Copy

import requests
import json

BASE_URL = "https://geo.btaa.org/api/v1"

# Get spatial facets for a resource
resource_id = "ark28722-s7vs38"
response = requests.get(f"{BASE_URL}/resources/{resource_id}/spatial-facets")
data = response.json()

print(f"Spatial facets for resource: {resource_id}")
spatial_facets = data.get('spatial_facets', {})
if spatial_facets:
    if 'dcat_bbox' in spatial_facets:
        print(f"Bounding Box: {spatial_facets['dcat_bbox']}")
    if 'geo.country' in spatial_facets:
        country = spatial_facets['geo.country']
        print(f"Country: {country.get('name', 'N/A')}")
    if 'geo.region' in spatial_facets:
        regions = spatial_facets['geo.region']
        print(f"Regions: {', '.join([r.get('name', '') for r in regions])}")
    if 'geo.county' in spatial_facets:
        counties = spatial_facets['geo.county']
        print(f"Counties: {', '.join([c.get('name', '') for c in counties])}")
else:
    print("No spatial facets found.")

📋 Copy

Click "Run" to see the API response...

📋 Copy

Click "Run" to see the output...

▶ Run Example

Resource — Static Map

Resource Static Map

Resource

Goal: Get static map image for a resource.

Request: GET /api/v1/resources/{id}/static-map

Python Image Response Output

📋 Copy

import requests
import base64

BASE_URL = "https://geo.btaa.org/api/v1"

# Get static map image for a resource
resource_id = "ark28722-s7vs38"
response = requests.get(f"{BASE_URL}/resources/{resource_id}/static-map")

if response.status_code == 200:
    # Save the image
    with open('static_map.png', 'wb') as f:
        f.write(response.content)
    print(f"✅ Static map image saved for resource: {resource_id}")
    print(f"Content-Type: {response.headers.get('Content-Type', 'N/A')}")
    print(f"Image size: {len(response.content)} bytes")
else:
    print(f"❌ Error: {response.status_code}")

Click "Run" to see the image response...

📋 Copy

Click "Run" to see the output...

▶ Run Example

Resource — Thumbnail

Resource Thumbnail

Resource

Goal: Get thumbnail information for a resource.

Request: GET /api/v1/resources/{id}/thumbnail

Python API Response Output

📋 Copy

import requests
import json

BASE_URL = "https://geo.btaa.org/api/v1"

# Get thumbnail for a resource
resource_id = "ark28722-s7vs38"
response = requests.get(f"{BASE_URL}/resources/{resource_id}/thumbnail", allow_redirects=False)

print(f"Thumbnail for resource: {resource_id}")
print(f"Status: {response.status_code}")
print(f"Content-Type: {response.headers.get('Content-Type', 'N/A')}")
print(f"Final URL: {response.url}")
print(f"Redirect location: {response.headers.get('Location', 'N/A')}")

📋 Copy

Click "Run" to see the API response...

📋 Copy

Click "Run" to see the output...

▶ Run Example

Resource — Viewer Data

Resource Viewer Data

Resource

Goal: Get viewer data for a resource.

Request: GET /api/v1/resources/{id}/viewer

Python API Response Output

📋 Copy

import requests
import json

BASE_URL = "https://geo.btaa.org/api/v1"

# Get viewer data for a resource
resource_id = "ark28722-s7vs38"
response = requests.get(f"{BASE_URL}/resources/{resource_id}/viewer")
data = response.json()

print(f"Viewer data for resource: {resource_id}")
viewer = data.get('viewer', {})
print(f"Viewer type: {viewer.get('protocol', 'N/A')}")
print(f"Viewer URL: {viewer.get('endpoint', 'N/A')}")

📋 Copy

Click "Run" to see the API response...

📋 Copy

Click "Run" to see the output...

▶ Run Example

Maps and Thumbnails Endpoints

Supports map geometry helpers and image retrieval endpoints used by frontend map and card UIs.

Method	Path	Notes
GET	/api/v1/map/h3	H3 map tile/geometry data
GET	/api/v1/static-maps/institutions/{map_id}	Institution static map
GET	/api/v1/static-map-assets/{map_hash}	Generated static-map asset by hash
GET	/api/v1/static-maps/{resource_id}/geometry	Resource geometry for static-map rendering
GET	/api/v1/static-maps/{resource_id}/resource-class-icon	Resource-class icon used by static-map rendering
GET	/api/v1/static-maps/{resource_id}	Resource static map
GET	/api/v1/thumbnails/placeholder	Placeholder thumbnail
GET	/api/v1/thumbnails/{resource_id}	Thumbnail by resource ID

Interactive Example: Placeholder Thumbnail

Placeholder Thumbnail

Maps/Thumbs

Goal: Retrieve the placeholder thumbnail metadata.

Request: GET /api/v1/thumbnails/placeholder

Python API Response Output

Copy

import requests
import json

BASE_URL = "https://geo.btaa.org/api/v1"

response = requests.get(f"{BASE_URL}/thumbnails/placeholder")
print(f"Status: {response.status_code}")
print("Content-Type:", response.headers.get("Content-Type"))

if "application/json" in (response.headers.get("Content-Type") or ""):
    print(json.dumps(response.json(), indent=2))
else:
    print("Binary/image response received.")

Copy

Click "Run" to see the API response...

Copy

Click "Run" to see the output...

Run Example

Parameters

Name	Type	Req?	Description
map_id	string	endpoint-specific	Institution map identifier for /static-maps/institutions/{map_id}
resource_id	string	endpoint-specific	Resource identifier for /static-maps/{resource_id} and /thumbnails/{resource_id}
map_hash	string	endpoint-specific	Cache key/hash for /static-map-assets/{map_hash}

OGM and Harvest Status Endpoints

Read-only endpoints for OpenGeoMetadata repository listing and harvest failure visibility.

Method	Path	Notes
GET	/api/v1/ogm/repos	Enabled/known OGM repositories
GET	/api/v1/ogm/harvest/failures	OGM harvest failure summary

Interactive Example: OGM Repositories

OGM Repositories

OGM

Goal: List OpenGeoMetadata repositories known to the API.

Request: GET /api/v1/ogm/repos

Python API Response Output

Copy

import requests
import json

BASE_URL = "https://geo.btaa.org/api/v1"

response = requests.get(f"{BASE_URL}/ogm/repos")
data = response.json()

print(f"Status: {response.status_code}")
if isinstance(data, dict):
    print("Top-level keys:", list(data.keys()))

Copy

Click "Run" to see the API response...

Copy

Click "Run" to see the output...

Run Example

Response notes

• /ogm/repos returns repository-level records used to track OGM ingestion sources.
• /ogm/harvest/failures returns recent failures for monitoring and debugging harvest issues.

OGC API Endpoints

The OGC API surface exposes standards-aligned discovery and records access endpoints.

Method	Path	Notes
GET	/api/v1/ogc/	OGC API landing page
GET	/api/v1/ogc/conformance	OGC conformance classes
GET	/api/v1/ogc/collections	Collections listing
GET	/api/v1/ogc/collections/btaa-records	BTAA records collection
GET	/api/v1/ogc/collections/btaa-records/queryables	Queryable fields
GET	/api/v1/ogc/collections/btaa-records/sortables	Sortable fields
GET	/api/v1/ogc/collections/btaa-records/items	Collection items
GET	/api/v1/ogc/collections/btaa-records/items/{recordId}	Single OGC record

Interactive Example: OGC Collections

OGC Collections

OGC

Goal: Retrieve OGC collection metadata.

Request: GET /api/v1/ogc/collections

Python API Response Output

Copy

import requests
import json

BASE_URL = "https://geo.btaa.org"

response = requests.get(f"{BASE_URL}/api/v1/ogc/collections")
data = response.json()

print(f"Status: {response.status_code}")
print("Collections:", len(data.get("collections", [])))

Copy

Click "Run" to see the API response...

Copy

Click "Run" to see the output...

Run Example

Parameters

Name	Type	Req?	Description
recordId	string	endpoint-specific	Resource ID for /api/v1/ogc/collections/btaa-records/items/{recordId}

Model Context Protocol (MCP) Endpoint

Provides an MCP-compatible response for clients integrating the API through MCP conventions.

Method	Path	Notes
GET	/api/v1/mcp	Model Context Protocol endpoint

Interactive Example: MCP Endpoint

MCP Endpoint

MCP

Goal: Fetch the Model Context Protocol endpoint payload.

Request: GET /api/v1/mcp

Python API Response Output

Copy

import requests
import json

BASE_URL = "https://geo.btaa.org/api/v1"

response = requests.get(f"{BASE_URL}/mcp")
data = response.json()

print(f"Status: {response.status_code}")
print("Response type:", type(data).__name__)

Copy

Click "Run" to see the API response...

Copy

Click "Run" to see the output...

Run Example

Response notes

• Intended for machine clients and tooling that expect MCP-compatible endpoint behavior.
• Keep response handling tolerant to additive fields as MCP support evolves.