HPS Geospatial

Overview

A constrained spatial rendering API.

The API supports the same poster workflow as the Studio. It operates on registered regional HydroRIVERS data and named geoBoundaries records; it is not a general-purpose GIS service or arbitrary data-upload endpoint.

Runtime coverage: South America and North/Central America
Preview: SVG at a 2400 x 3600 canvas
Export: SVG, PNG, and PDF presets

Architecture

One geometry path, one composition model.

Preview and export use the same request model and SVG renderer. Export adds a conversion step and an audit manifest after the composition has been generated.

01
Resolve
Load the selected boundary and preset definitions.
02
Clip
Intersect HydroRIVERS line geometries in PostGIS.
03
Classify
Map river hierarchy into display classes.
04
Compose
Generate the poster through the shared SVG renderer.
05
Deliver
Return preview SVG or convert the export.

Quick start

Resolve IDs before rendering.

Geography and preset IDs are data-driven. Read the registries first rather than hard-coding a display name.

1. Set the API origin

export API_BASE="https://hydro-backend-54n4ik523a-uc.a.run.app"

2. Read geographies and presets

curl "$API_BASE/geographies"
curl "$API_BASE/presets"

3. Request a preview

curl -X POST "$API_BASE/preview" \
  -H "Content-Type: application/json" \
  -d '{
    "geography_id": "<admin_0_id>",
    "density_preset": "balanced",
    "classification_preset": "standard",
    "style": {
      "schema_version": 2,
      "mode": "standard",
      "preset_id": "abyss",
      "overrides": {}
    },
    "typography": "gallery_poster",
    "title": "FLOWING GUYANA",
    "subtitle": "River Network of Guyana",
    "metadata_options": {
      "show_title": true,
      "show_subtitle": true,
      "show_legend": true,
      "show_north_arrow": true,
      "show_scale_bar": true,
      "show_data_credits": true
    }
  }' \
  --output preview.svg

Render request

POST /preview

Returns the composed poster as image/svg+xml. Use it for review and interactive layout work before requesting the final export.

Core fields

geography_id: Required registered boundary ID.
density_preset: Network density and classification rules.
style: Versioned standard or flag-derived palette selection.
typography: Registered typography preset ID.
metadata_options: Granular poster-element visibility.
layout_overrides: Optional element x, y, and scale overrides.

Response contract

Content-Type: image/svg+xml
X-River-Count: Number of retained river features.
X-Geography-Name: Resolved display name.
X-Feature-Summary: Feature counts by display class.

Export request

POST /export

Uses the render fields plus format and size settings. The response body is the file itself; filename and manifest data are returned in headers.

curl -X POST "$API_BASE/export" \
  -H "Content-Type: application/json" \
  -d '{
    "geography_id": "<admin_0_id>",
    "density_preset": "balanced",
    "classification_preset": "standard",
    "style": {
      "schema_version": 2,
      "mode": "standard",
      "preset_id": "abyss",
      "overrides": {}
    },
    "typography": "gallery_poster",
    "title": "FLOWING GUYANA",
    "subtitle": "River Network of Guyana",
    "export_format": "png",
    "export_size": "high_res_poster"
  }' \
  --output poster.png

Export sizes

digital_poster, high_res_poster, instagram_portrait, print_18x24, square_design_asset, or custom.

Response headers

Content-Disposition provides the filename. X-Export-Manifest records the resolved inputs, sources, canvas, rule versions, feature summary, and output hash.

Preset registry

GET /presets

Returns the currently available density, palette, typography, and flag-derived style definitions. Treat these IDs as the source of truth for request construction.

Density

Filtering thresholds and stream-order-to-display-class mapping.

Palette

Background, feature hierarchy, and text color tokens.

Typography

Registered title and subtitle font, weight, and tracking values.

Errors and limits

Validate the combination, not only each field.

Common responses

404: Unknown geography or density preset.
422: Invalid request, style, export size, or format combination.
503: Database unavailable or not ready.
500: Unexpected processing or conversion failure.

Current limits

Custom output: shortest side at least 1000 px; longest side at most 9000 px.
Transparent design assets support PNG and SVG, not PDF.
Runtime data is regional; global HydroRIVERS is not queried.
Source line geometries are repaired at rest where available; the fallback clipping path applies ST_MakeValid.

Glossary

Terms used by the API.

Display class: Cartographic rank assigned to a river line, such as major, primary, secondary, minor, or headwater.
Stream order: HydroRIVERS hierarchy value used by density presets to retain and classify network features.
Style selection: Versioned palette choice containing mode, preset ID, optional variant, and token overrides.
Design asset mode: Transparent output mode that removes poster text and cartographic annotation.
Layout override: Optional x, y, and scale adjustment for a supported poster element.
Export manifest: JSON response header describing resolved inputs, rules, sources, output dimensions, and SHA-256 hash.

Reference

Interactive API schema

The backend-hosted Swagger UI reflects the poster-generation API used by this public product surface.

Build with the Hydro Poster rendering pipeline.