Response Formats

Overview of supported response formats, media-type handling, and JSON/HTML behavior in the NLDI.

Overview

The NLDI returns GeoJSON by default. The ?f= query parameter controls the response format.

Format Options

Parameter	Behavior
`?f=json`	Returns GeoJSON (`application/json`). Recommended for all requests.
`?f=html`	Returns a stub HTML page with a link to the JSON version. Not a full browsable view.
(omitted)	Returns GeoJSON. Programmatic clients (curl, Python, R) receive JSON by default.

JSON-LD (?f=jsonld) is accepted by the API but currently returns plain JSON without @context or linked-data semantics. JSON-LD support is not functional in the Python implementation.

The API silently ignores unknown ?f= values and returns JSON.

Browser vs. Programmatic Clients

When a browser sends an Accept header preferring text/html, the API returns the HTML stub page rather than raw JSON. To retrieve JSON in a browser, append ?f=json:

https://api.water.usgs.gov/nldi/linked-data/nwissite/USGS-05428500?f=json

Programmatic clients that do not send an HTML-preferring Accept header receive JSON by default — no ?f= parameter is strictly required, but including ?f=json is good practice for clarity.

Response Structure

Typical GeoJSON responses follow this structure:

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

Feature properties vary by endpoint. For example, a registered feature includes identifier, name, uri, comid, reachcode, measure, source, sourceName, and navigation (a URL to navigate from that feature). Navigation flowline results include a smaller set: nhdplus_comid, mainstem, source, and sourceName.