Response Formats

Overview

The NLDI provides responses in multiple formats depending on the request headers
and URL parameters. By default, responses follow a JSON representation of
GeoJSON feature collections.

In 2020, the NLDI introduced updated media-type handling to improve the
user experience and reduce accidental loading of very large JSON documents in
web browsers.

Browser-Friendly Fallback

When a request is made from a web browser (i.e., using an Accept header that
prefers text/html), the NLDI now returns a short HTML document instead
of raw JSON.

This HTML response includes:

• A user-friendly message
• A link to the JSON content

This prevents browsers from loading large GeoJSON payloads directly.

Forcing JSON Output

To explicitly retrieve JSON regardless of client headers, append:

?f=json

to any request.
This overrides the HTML fallback and ensures JSON is returned even in browsers.

Example pattern:

/linked-data/{featureSource}/{featureID}?f=json

Default Response Content

By default (no Accept header indicating HTML, no format override),
the NLDI returns GeoJSON.

GeoJSON responses follow typical patterns such as:

{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "geometry": { ... },
      "properties": { ... }
    }
  ]
}

Example response structures can be seen when retrieving registered features or
navigation flowlines.

Supported Format Options (Current Behavior)

Based on the documented update behavior, the following formats are supported:

• f=json — Forces JSON output
• HTML fallback — Returned only when browser Accept headers prefer HTML

TODO: Add final confirmation of Python implementation support for:

• JSON-LD
• Any additional format parameters exposed by pygeoapi or future NLDI versions

Summary of Media-Type Rules

• Browser clients receive HTML fallback unless ?f=json is explicitly provided.

• Programmatic clients (scripts, Python, R, curl) receive JSON by default.

• Any request may use ?f=json to guarantee JSON output.

Notes & TODOs

• TODO: Confirm JSON-LD support in the Python-backed NLDI API.
• TODO: Add a concise table of all final ?f= options once implementation is fixed.