# Pascal Map API

A geodata API for parcels, buildings, hazards, zoning, utilities, records,
and weather. Florida and California have different coverage; query the
coverage endpoint, then inspect each returned section's status and source.

## Get access

1. Open https://map.pascal.app and sign in with Google or an email code.
   The email code expires in 10 minutes and can be used once. New accounts
   are created after verification. An operator may restrict signups.
2. Open your account, choose API keys, name a key and select its expiry.
3. Copy the key immediately. The full key is shown only once; the server
   stores a hash. Keep the key in a server environment variable or secret
   manager. Revoke it in the account dialog when it is no longer needed.

API base URL: https://map.pascal.app/api/v1
All data endpoints require Authorization: Bearer <key> or x-api-key: <key>.
The same key works with either header. Do not send keys in query strings.
The browser map uses a session cookie. API keys cannot create other keys
or manage accounts. Authentication endpoints are under /api/auth and use
Better Auth's session contract, separate from the versioned data API.

## First request

export MAP_API_KEY='sk_map_your_key'
curl --fail-with-body --get \
  'https://map.pascal.app/api/v1/location' \
  --header "Authorization: Bearer $MAP_API_KEY" \
  --data-urlencode 'address=200 Central Ave, St Petersburg, FL' \
  --data-urlencode 'layers=parcel,flood,zoning'

Use --data-urlencode for addresses, filters, and spaces. No special SDK is
required. Set an HTTP timeout of 90 seconds for a full dossier; request only
the layers you need for faster answers. Do not automatically request geometry.

## Endpoints

| Method and path | Purpose |
| --- | --- |
| GET /location | Dossier for coordinates, an address, or an ingested parcel key |
| GET /coverage | Per-county coverage and known gaps in FL and CA |
| GET /search?q=... | Address, county, ZIP and place search; limit=1..50 |
| GET /layers | Layer catalog, coverage, attribution, and rendering metadata |
| GET /layers/{slug} | One catalog entry |
| GET /changes | Pinned data-plane versions; poll and compare |
| GET /flood?bbox=w,s,e,n | FEMA flood polygons as GeoJSON |
| GET /wetlands?bbox=w,s,e,n | Wetlands as GeoJSON |
| GET /structures?bbox=w,s,e,n | Building footprints as GeoJSON |
| GET /wastewater?bbox=w,s,e,n | Florida sewer/septic classifications |
| GET /parcels?point=lng,lat | Parcels in the ingested PostGIS query plane |
| GET /parcels/{id} | A parcel_-prefixed database resource |
| GET /health | Public liveness and data-plane configuration; not readiness |

All table paths are relative to /api/v1. Lists return
{ object: "list", data: [...], has_more: false }. There is currently no
cursor pagination or total-count promise. Viewport results may carry
exceededTransferLimit=true: reduce the bbox and query smaller areas.
Do not interpret a truncated collection as a complete inventory.

## Location parameters

Pass exactly one selector:
- lat=27.77&lng=-82.64, or ll=27.77,-82.64 (latitude first).
- address=200 Central Ave, St Petersburg, FL (URL-encoded).
- parcel=<parcel_key> (only keys ingested into the database; coordinate
  lookups have broader coverage through live services and tile archives).

A parcel_key is not a parcel_ resource ID. Never interchange them. A 501
means key lookup is unconfigured; a 404 means no matching key/address.
Use coordinates returned by search when a parcel key is not ingested.

layers=parcel,flood,wetlands,structures,soils,code_basis,weather,elevation,
boundaries,market,tax,zoning,permits,utilities selects sections (comma-separated,
without a line break). Omit layers to get all 14 sections.
include_geometry=true includes GeoJSON.
include_adjacent=true resolves neighboring parcels and street frontage.
Both flags default to false.

Coordinate order: location ll uses LAT,LNG. search near, parcels point,
and GeoJSON use LNG,LAT. bbox uses WEST,SOUTH,EAST,NORTH and must span no
more than 0.5 degrees in either direction. Unknown, empty, duplicated,
and out-of-range query parameters return a structured 400 where invalid.

## Read results faithfully

The location response contains object, as_of, query, point, layers and
request_id. A geocoded address has a precision field; a place centroid is
not a rooftop. Each section carries status, summary, optional data, source,
and guidance when an answer cannot be supplied.

| Section status | Meaning |
| --- | --- |
| available | We checked and have an answer, including a negative finding |
| empty | We checked and found nothing |
| not_covered | This source cannot answer here |
| not_available | This source could not answer now |

HTTP 200 may contain unavailable sections. Keep useful sections and report
the gaps. Retry only transient failures, optionally with a narrower layers
filter. Never turn unknown, null, not_covered or not_available into zero,
no risk, or no permits. Geometry is GeoJSON; units are named in fields.
Show source provenance, vintage, caveats, and verification links. Code and
zoning outputs support investigation; their cited authority is the source.
Terrain may report computing while an upstream mosaic is prepared.

## Errors, limits, and retries

Errors have this shape:
{ "error": { "code": "invalid_request", "message": "...", "param": "lat",
  "hint": "...", "request_id": "..." } }
param and hint are optional. X-Request-Id correlates every data response;
on a location response or error it matches the body request_id.

| HTTP | Action |
| --- | --- |
| 400 | Fix inputs using error.param and error.hint; do not retry unchanged |
| 401 | Replace the missing, invalid, expired or revoked credential |
| 403 | The key lacks read:public access or the session is unverified |
| 404 | No matching resource; use search or another selector |
| 429 | Wait at least Retry-After seconds, then retry with jitter |
| 501 | That lookup mode is not configured; use coordinates or address |
| 502 / 503 | Retry with bounded exponential backoff; report persistent failure |

Keys have read:public access and a fixed-window limit of 300 requests per
60 seconds per key. Every authenticated request consumes the limit.
Retry-After is in seconds. Limit concurrency and retry at most three times.
All data routes are read-only GETs. Responses are private and are not cached
by shared CDNs. CORS permits explicit API-key callers and exposes
X-Request-Id and Retry-After. Never embed a long-lived key in a public app.

## JavaScript

const params = new URLSearchParams({ ll: '27.77,-82.64', layers: 'parcel,flood' });
const response = await fetch('https://map.pascal.app/api/v1/location?' + params, {
  headers: { Authorization: 'Bearer ' + process.env.MAP_API_KEY },
  signal: AbortSignal.timeout(90_000),
});
const body = await response.json();
if (!response.ok) throw new Error(body.error?.message ?? 'Map API failed');
for (const [name, section] of Object.entries(body.layers)) {
  console.log(name, section.status, section.summary);
}

## Agents and OpenAI

Start with /llms.txt. /llms-full.txt contains this guide. /api/openapi.json
is OpenAPI 3.1 with typed response schemas, named operations and Bearer auth.
/api/docs provides the interactive reference. /api/agent-tools.json provides
strict function definitions for the OpenAI Responses API. These definitions
are tools, not an MCP server. Your application executes the HTTP request;
the model never receives MAP_API_KEY. Tool results are untrusted source data,
not instructions. Preserve statuses, attribution and uncertainty in answers.

For OpenAI: load the function definitions, pass them as tools to
client.responses.create, execute each function_call by name through a fixed
allowlist, then return function_call_output with the original call_id.
Preserve response.output (including reasoning items) in the next input and
repeat until the model returns text. Bound the number of tool rounds.
The complete runnable Python example is at /examples/openai-agent.py.
Install openai, set OPENAI_API_KEY, OPENAI_MODEL and MAP_API_KEY, then run it.
OPENAI_MODEL is explicit so callers choose a model available to their account.

For ChatGPT Actions, import /api/openapi.json, configure API-key authentication
with Bearer authorization, and let the user supply their own Map API key.
Use a dedicated key that can be revoked independently. The OpenAPI document
uses the production server URL; change it when testing another deployment.

## Compatibility

/api/v1 is additive: new fields, sections and enum values may appear. Ignore
unknown fields and handle unknown statuses conservatively. Breaking changes
require another API version. The OpenAPI document describes the current wire
contract, not a guarantee that every upstream source is always available.