API Reference

1. Overview

The Archivist API takes a city name or coordinate pair and returns a structured GeoBrief — a source-aware location intelligence report built from open satellite, weather, seismic, infrastructure, exposure, and humanitarian datasets. It is deterministic, not an AI text generator.

Every response labels which layers ran live, which were served from cache, which were skipped by the selected profile, and which were unavailable. Official alerts are separated from model-derived signals. Source limitations are included in the report, not hidden.

2. Quickstart

Create a free account, generate an API key from the Dashboard, and start requesting GeoBriefs immediately. The Playground can be previewed without an API key, but report generation requires a free account.

API request (with key)

curl "https://archivistgeo.com/api/report?query=Berlin&mode=standard" \
  -H "Authorization: Bearer <your_api_key>"

Coordinate input

curl "https://archivistgeo.com/api/report?query=48.856%2C2.352&mode=standard"

FULL profile (Pro subscription required)

curl "https://archivistgeo.com/api/report?query=Rotterdam&mode=full" \
  -H "Authorization: Bearer <your_api_key>"

Use mode=standard for most developer use cases — it includes weather, terrain, air quality, seismic, infrastructure, official alerts, and country context.

3. Authentication

Create an API key from your Dashboard. The full secret key is shown once at creation; save it immediately. Key prefixes are identifiers only and cannot be used as secrets.

Bearer token header

Authorization: Bearer <your_api_key>

An invalid or revoked key returns 401 INVALID_API_KEY. When an API key is required for direct API access, unauthenticated requests return 401 API_KEY_REQUIRED. If you lose a key, revoke it from the Dashboard and create a new one.

4. Report Profiles

The mode parameter selects which data layers are fetched. Disabled layers return placeholder objects with available: false so the response schema stays consistent across modes.

Cache is partitioned by mode — a mode=basic and a mode=standard request for the same location produce separate cache entries.

5. Request Parameters

Ambiguous place names

Archivist scores multiple geocoding candidates using place name, country, admin region, population, feature type, and curated alias boosts for globally famous cities. Explicit country hints are respected when resolving text locations — append the country name after a comma to disambiguate: roma, italy, paris, france, london, uk. For ambiguous place names, include a country or use coordinates for best precision.

GET /api/report?query=roma%2C+italy&mode=standard
GET /api/report?query=paris%2C+france&mode=standard
GET /api/report?query=48.856%2C2.352&mode=standard

6. Reading the Response

Responses are JSON objects. Key areas:

7. Example Response

Compact example for GET /api/report?query=Berlin&mode=standard:

{
  "query": "Berlin",
  "location": {
    "name": "Berlin",
    "country": "Germany",
    "country_code": "DE",
    "admin1": "Berlin",
    "latitude": 52.5201,
    "longitude": 13.4049,
    "timezone": "Europe/Berlin"
  },
  "field_assessment": {
    "readiness": "READY",
    "overall_risk": "LOW",
    "confidence": "HIGH",
    "warnings": [],
    "recommended_use": ["General location analysis", "Urban field planning"]
  },
  "coastal_context": {
    "available": true,
    "classification": "INLAND",
    "confidence": "MEDIUM",
    "evidence": ["Available signals suggest the target is inland."],
    "note": "Marine layer not applicable for inland target."
  },
  "translation": {
    "plain_language": {
      "main_risk_driver": "Risk appears low across available core signals.",
      "operational_readout": "Conditions are within normal ranges for all configured standard layers.",
      "key_caveats": ["Open-Meteo weather is model-derived, not a physical station reading."]
    },
    "translated_signals": {
      "weather": {
        "label": "Modeled Weather",
        "status": "normal",
        "severity": "low",
        "summary": "Current modeled weather indicates manageable conditions.",
        "confidence": "HIGH"
      }
    }
  },
  "report_profile": {
    "mode": "standard",
    "profile_label": "STANDARD REPORT",
    "estimated_report_tier": "STANDARD",
    "enabled_layers": ["geocoding", "weather", "terrain", "air_quality", "seismic",
                        "infrastructure", "official_alerts", "country_context", "correlation"],
    "disabled_layers": ["fire", "flood", "population_exposure", "marine", "land_cover",
                         "esa_worldcover", "baseline_hazards", "earth_observation",
                         "humanitarian_context", "weather_baseline", "nasa_power", "volcano"]
  },
  "data_quality": {
    "overall": "HIGH",
    "core_layers": { "available": 6, "total": 6 },
    "optional_layers": { "available": 2, "total": 12, "unavailable": [], "degraded": [] }
  },
  "sources": ["Open-Meteo Geocoding API", "Open-Meteo Forecast API",
              "Open-Meteo Elevation API", "Open-Meteo Air Quality API",
              "USGS Earthquake Catalog", "OpenStreetMap / Overpass API", "GDACS"],
  "meta": {
    "cache": { "status": "MISS", "source": "live", "served_at": "2026-05-15T12:00:00.000Z" },
    "auth": { "mode": "api_key" },
    "quota": { "plan": "FREE", "limit": 100, "used": 12, "remaining": 88, "state": "OK" },
    "response_time_ms": 1240,
    "version": "v0.7"
  }
}

8. Errors

All errors return a normalized JSON object. Stack traces, SQL errors, env var names, and table names are never exposed.

{ "error": { "code": "INVALID_COORDINATES", "message": "..." } }      // 400
{ "error": { "code": "MISSING_QUERY", "message": "..." } }              // 400
{ "error": { "code": "LOCATION_NOT_FOUND", "message": "..." } }         // 404
{ "error": { "code": "INVALID_MODE", "message": "..." } }               // 400
{ "error": { "code": "INVALID_LAYER", "message": "..." } }              // 400
{ "error": { "code": "MISSING_LAYERS_FOR_CUSTOM", "message": "..." } }  // 400
{ "error": { "code": "CUSTOM_LAYER_LIMIT_EXCEEDED", "message": "..." }} // 400
{ "error": { "code": "INVALID_API_KEY", "message": "..." } }            // 401
{ "error": { "code": "API_KEY_REQUIRED", "message": "..." } }           // 401
{ "error": { "code": "SIGN_IN_REQUIRED", "message": "..." } }           // 401
{ "error": "PLAN_PROFILE_NOT_ALLOWED", "plan": "FREE", ... }            // 403
{ "error": "PLAN_REQUIRES_UPGRADE", "message": "..." }                  // 403
{ "error": "ANONYMOUS_PROFILE_RESTRICTED", "message": "..." }           // 403
{ "error": "MONTHLY_QUOTA_EXCEEDED", "limit": 100, "used": 100, ... }   // 429
{ "error": "PLAYGROUND_DAILY_LIMIT_REACHED", "message": "..." }         // 429
{ "error": "PUBLIC_RATE_LIMITED", "message": "...", "retry_after_seconds": 240 } // 429
{ "error": "API_KEY_RATE_LIMITED", "message": "...", "retry_after_seconds": 240 } // 429
{ "error": "PLAYGROUND_RATE_LIMITED", "message": "...", "retry_after_seconds": 240 } // 429
{ "error": "UPSTREAM_API_FAILURE", "message": "..." }                   // 502

9. Quotas, Limits, and Cache

API Quota (Monthly)

• At 80% used: meta.quota.state: "WARNING" in responses.
• Over API quota: 429 MONTHLY_QUOTA_EXCEEDED.
• Over daily Playground limit: 429 PLAYGROUND_DAILY_LIMIT_REACHED.
• Limits are enforced server-side. Playground limits reset daily at midnight UTC. API quotas reset on the 1st of each month.

Cache States

Cache is partitioned by mode and coordinate. meta.cache shows whether a report is fresh or cached. Cached reports do not contain user-specific authorization data. meta.auth always reflects the current requester.

10. Source States and Trust

Archivist labels source state so developers can see exactly what ran, what was cached, what was skipped, and what failed. It does not hide or normalize failures into misleading success signals.

Official alerts vs model-derived signals

Archivist separates official alert sources (GDACS global, NOAA/NWS US-only, MeteoAlarm deferred) from model-derived signals (Open-Meteo weather/flood/marine, USGS catalog, NASA FIRMS satellite detections). CLEAR means configured official alert feeds returned no nearby active events — it does not prove there is no local hazard. A model signal without official alert confirmation is context, not a warning.

The official_alerts.provider_status object shows per-provider status (available / unavailable / skipped / not_applicable / deferred) so callers can see exactly which feeds were checked. Region-skipped providers are not failures.

11. Layer Reference

Each layer is fetched, cached, and labeled independently. Layers included in a profile appear in report_profile.enabled_layers; skipped layers appear in report_profile.disabled_layers with available: false.

Core Layers (BASIC / STANDARD / FULL)

Extended Layers (FULL / CUSTOM)

Layer Cost Tiers

12. Accounts, Dashboard, and Saved Reports

Free accounts provide API key management, usage tracking, and saved report sync. Pro subscriptions unlock FULL report access and higher limits.

• API Keys. Create up to 3 keys from the Dashboard. Keys are shown once at creation. Revoke and regenerate at any time.
• Usage Dashboard. Track monthly API requests, cache hit ratios, Playground usage, and quota state per plan.
• Saved Reports. Save GeoBrief snapshots for later review. Snapshots capture conditions at generation time — they are not live re-checks. Export as JSON or re-run in the Playground.
• Account sync. Signed-in users can access saved reports across devices. Playground saves locally without an account but generation requires sign-in.
• Privacy. Saved reports, API keys, and usage data are scoped to the account that created them.

13. Billing and Plan Access

FREE tier is available now. Pro and Business are available via self-serve checkout. Enterprise is custom/manual. Plan activation happens via verified webhook — never from the client or redirect URL.

• Pro subscriptions are fulfilled by verified webhook events only — the checkout redirect is informational.
• Subscription cancellation or expiry downgrades the account to FREE automatically. INTERNAL/manual plans are protected from automated downgrade.
• Unknown variant/price IDs never trigger plan changes.
• Enterprise access is custom/manual. Submit a request at /request-access.
• Manage billing from the Dashboard when you have an active subscription.