Developer docs
Lotmark's REST API exposes source-cited parcel enrichment records. Discover available releases and jurisdictions through the authenticated dataset catalog, then use the REST reference below to verify lookup behavior, response shape, provenance, and batch workflows.
Connect your agent with Lotmark's MCP tools, or use the REST reference below.
Parcel intelligence.
Inside your agent.
Give Claude or Codex read-only tools to discover parcel datasets, look up properties, inspect source citations and QA, and enrich a batch of parcels. Returned fields depend on the approved dataset and its source coverage.
MCP endpoint: https://api.lotmark.io/mcp
The MCP uses Authorization: Bearer with your existing customer API key on every request. No OAuth sign-in or local server package is required.
Already have a Lotmark API key? Use it here. Otherwise request a key through developer access or checkout. Keep credentials out of contact forms, shared configuration, URLs, and chat messages.
Supply your key privately
For Claude Code and Codex, set LOTMARK_API_KEY in the environment that launches the client. This Bash / zsh prompt hides your input and keeps the key out of shell history. Run it in your own terminal, then start the chosen client in that same terminal. A secret manager may supply the variable instead.
Enter your own key only at the hidden terminal prompt. This website never receives it. Environment variables last for that shell session.
Claude Code
Merge this server entry into your project's .mcp.json, preserving any existing servers. Claude Code expands the environment reference in the header. Launch claude from the shell holding your key, approve the project server if prompted, and use /mcp to inspect status and tools.
Select and copy this text manually, or use the copy button. Configuration contains environment references, never your key.
Codex
With the Codex CLI installed, register the server below. The token flag stores the environment-variable name, not the key. Launch codex from the shell holding your key; use /mcp to inspect active servers.
Select and copy this text manually, or use the copy button. Configuration contains environment references, never your key.
Configure Codex directly in TOML
Merge into ~/.codex/config.toml, or a trusted project's .codex/config.toml. Desktop/IDE clients must receive LOTMARK_API_KEY in their launch environment too; restart after configuring it.
Select and copy this text manually, or use the copy button. Configuration contains environment references, never your key.
Claude web / Desktop remote connector
This uses your Claude account’s remote connector settings, separately from Claude Code. It requires an HTTPS endpoint reachable from Anthropic’s cloud. Use the endpoint shown above.
- Open Customize → Connectors → Add custom connector and name it Lotmark. Organization owners manage this under organization connector settings.
- Enter the public MCP URL. Select No sign in for OAuth, since Lotmark uses a bearer key.
- Under Request headers, set header name
Authorizationand privately enterBearerfollowed by your own Lotmark key. Environment references are for CLI clients; enter the real value only in Claude’s private credential setting. - Add the connector and enable it for a conversation. Verify tool discovery and a read-only call.
On Team/Enterprise, a fixed connector credential is shared by its users. Use an organization-approved key with appropriate access. Local Desktop claude_desktop_config.json is a separate mechanism; this HTTP server has no local stdio launcher.
These instructions match the server’s HTTP and bearer-key contract. Client connection verification is separate: copying or saving configuration does not prove initialization, tool discovery, or a successful parcel lookup.
Prerequisites and connection contract
- An active customer API key issued by Lotmark and the exact configured MCP URL. A revoked or unknown key is rejected on every request.
- An installed and signed-in Claude Code or Codex client that supports Streamable HTTP. Remote Claude connectors require account/workspace permission and access from Anthropic's cloud.
- The server lives in the parcel API at
/mcp, using the official Python MCP SDK. It serves stateless Streamable HTTP with JSON responses and bearer-key authentication. REST endpoints and the website’s/docsare separate routes. - Only approved, explicitly non-synthetic dataset releases whose QA status is
passorwarningare exposed. Source attribution, release IDs, licensing, missing fields, and warnings are preserved in results. - Parcel lookups use the existing REST request accounting. Read-only access can still record usage; no administrative, ingestion, billing, or arbitrary upstream-request tools are exposed.
- The API key is sent in an HTTPS header. Supply it through your client’s private credential setting or launch environment. Never put it in a URL, public asset, source control, analytics, logs, or screenshots.
MCP tool catalog
list_datasets- No arguments. Discover approved datasets, jurisdictions, releases, and available source layers.
get_datasetdataset_id. Inspect a dataset’s release, sources, and licensing before lookup.get_parcelparcel_id. Retrieve a source-cited parcel enrichment record.get_parcel_by_apnapn, optionaldataset_idorcounty_fips. Scope the APN to its jurisdiction; ambiguous matches require a more specific lookup.search_parcelsaddress,limit(default 10, maximum 25), and requireddataset_idorcounty_fips. Search addresses within that jurisdiction.batch_enrich_parcelsparcel_ids,apns,addresses, optionaldataset_idorcounty_fips. At most 100 total lookups; APNs and addresses require jurisdiction scope. Each APN returns up to 10 matches and each address up to 5; results are deduplicated by parcel ID. Use a smaller batch if your client truncates results.get_parcel_qaparcel_id. Inspect the parcel’s QA report and warnings.get_usage- No arguments. Inspect request counts for your current key.
Verify the connection
- Open the client’s MCP status and confirm initialization succeeds. Check discovery against the eight tools above; an HTTP health check or a saved config is insufficient.
- Call
list_datasets, thenget_datasetusing a returneddataset_id. Confirm release identity, jurisdiction, and distribution/source details. - Use a real APN or address available to your account, scoped to that returned dataset. Call
get_parcel_by_apnorsearch_parcels, then inspect a returned record withget_parcelandget_parcel_qa. - Compare parcel identifiers,
sources,field_sources, and release metadata with their provenance. Keep missing fields explicit; empty results are not substitute records. Checkget_usageto confirm accounting.
Troubleshooting
- 401 / missing or invalid bearer key: check that
LOTMARK_API_KEYis exported in the client’s launch environment and the key remains active. Restart the client after changing its environment. For remote Claude, check the privateAuthorizationrequest header. - Initialization or discovery fails: confirm the exact
/mcpURL, HTTPS reachability, and Streamable HTTP transport. A browser GET or REST response alone does not test MCP initialization. - Ambiguous APN or missing jurisdiction: pass the real
dataset_idfrom discovery or the correctcounty_fips. APNs can repeat across counties and geometries. - Dataset/parcel not found: inspect the public catalog and release approval; an unapproved or synthetic dataset is unavailable. Do not replace a missing result with an invented parcel.
- Batch rejected or truncated: stay within 100 combined inputs, supply scope for APNs/addresses, and use smaller batches within your client’s output limits.
- Remote Claude cannot connect: verify a public HTTPS route and request headers; a VPN, loopback URL, or firewall can block access from Anthropic’s cloud. Ask your workspace administrator about connector permissions.
- Copy is unavailable: use “Select text for manual copy,” then your device’s copy action or Ctrl+C / Command+C. Text fields remain copyable without JavaScript.
Base URLs
Parcel API: https://api.lotmark.io
Public site and access requests: https://lotmark.io
The parcel API is a separate protected service. Use the parcel API base URL for every /v1 request, not the public landing page URL.
Interactive OpenAPI docs are available on the parcel service at https://api.lotmark.io/docs. The machine-readable schema is available at https://api.lotmark.io/openapi.json.
Current Coverage
Discover current REST availability with GET /v1/datasets and approved MCP availability with list_datasets. The catalogs report loaded release IDs, jurisdictions, and source coverage; local acquisition files do not establish production availability. The source metrics below describe the deployed Sonoma release.
- Sonoma parcel records: 189,239.
- Sonoma enrichment: hazard, terrain, soil, and canopy coverage as detailed below.
- Canopy: 189,239 parcels from USDA Forest Service NLCD Tree Canopy Cover 2023 raster sampling.
- Terrain: 189,233 elevation rows and 189,186 slope rows from USGS 3DEP 30 m raster sampling.
- Wildfire hazard potential: 189,239 parcels from USDA Forest Service WHP 2023 raster sampling.
- Soil: 189,213 parcels with SSURGO
mukey; 183,924 with hydrologic group from USDA NRCS SDA attributes. - Hazards: 40,969 CAL FIRE FHSZ rows, 184,594 FEMA flood-zone rows, and 171,407 burn-distance rows.
Authentication
All /v1 endpoints require a bearer API key. Keep the key in server-side secrets and send it with each request:
Authorization: Bearer LOTMARK_API_KEY
GET /health is open and can be used before credentials are provisioned. API keys are issued for sandbox evaluation or through checkout, and are shown once at delivery.
Endpoint Table
| Method | Path | Auth | Purpose |
|---|---|---|---|
GET |
/health |
No | Checks that the parcel API service and database are configured. |
GET |
/v1/parcels/:parcel_id |
Yes | Returns one curated parcel enrichment record by Lotmark parcel ID. |
GET |
/v1/parcels/by-apn/:apn |
Yes | Looks up a parcel by county APN and returns the same enrichment shape. |
GET |
/v1/parcels/search?address=...&limit=10 |
Yes | Searches loaded parcel addresses. limit is clamped from 1 to 25. |
POST |
/v1/parcels:batch-enrich |
Yes | Resolves parcel IDs, APNs, and address queries in one request. Maximum 100 total lookups. |
GET |
/v1/parcels/:parcel_id/qa |
Yes | Returns the persisted QA report for a generated parcel response. |
GET |
/v1/usage |
Yes | Returns request counts for the current API key. |
Curl Examples
Set the base URL and key once, then run the smoke tests below.
export LOTMARK_API_BASE="https://api.lotmark.io"
export LOTMARK_API_KEY="ltm_live_..."
curl -s "$LOTMARK_API_BASE/health"
curl -s -H "Authorization: Bearer $LOTMARK_API_KEY" "$LOTMARK_API_BASE/v1/parcels/lm_ca_028-030-009"
curl -s -H "Authorization: Bearer $LOTMARK_API_KEY" "$LOTMARK_API_BASE/v1/parcels/by-apn/028-030-009"
curl -s -H "Authorization: Bearer $LOTMARK_API_KEY" "$LOTMARK_API_BASE/v1/parcels/search?address=FRANZ%20VALLEY&limit=5"
curl -s -X POST "$LOTMARK_API_BASE/v1/parcels:batch-enrich" -H "Authorization: Bearer $LOTMARK_API_KEY" -H "Content-Type: application/json" -d '{"parcel_ids":["lm_ca_028-030-009"],"apns":["028-040-023"],"addresses":["PORTER CREEK RD"]}'
curl -s -H "Authorization: Bearer $LOTMARK_API_KEY" "$LOTMARK_API_BASE/v1/parcels/lm_ca_028-030-009/qa"
curl -s -H "Authorization: Bearer $LOTMARK_API_KEY" "$LOTMARK_API_BASE/v1/usage"
Response Shape
Parcel responses are JSON objects with source blocks on major sections, compact per-field source references, and an LLM-ready narrative grounded in structured fields. Embedding vectors are not returned by default; the response exposes embedding metadata.
{
"parcel_id": "lm_ca_001-011-004",
"freshness_days": 0,
"parcel": {
"apn": "001-011-004",
"address": "721 CLOVERDALE BLVD N",
"county": "Sonoma",
"state": "CA",
"land_acres": 0.77,
"source": {
"agency": "County of Sonoma",
"product": "Parcels Public",
"accessed": "2026-07-24",
"record_count": 189239
}
},
"risk_features": {
"fire": {
"wildfire_hazard_potential_value": 4,
"wildfire_hazard_potential_class": "high",
"distance_to_burn_perimeter_m": 792.7,
"last_burn_year_within_5km": 2021,
"source": {
"agency": "CAL FIRE",
"product": "California Fire Perimeters public view nearest feature within 5 km"
},
"confidence": 0.8
},
"flood": {
"fema_zone": "X",
"in_sfha": false,
"source": {
"agency": "FEMA",
"product": "National Flood Hazard Layer Flood Hazard Zones point intersect"
},
"confidence": 0.9
}
},
"building": {
"primary_year_built": 1952,
"primary_size_sqft": 4705,
"source": {
"agency": "County of Sonoma",
"product": "Parcels Public building attributes"
},
"confidence": 0.85
},
"terrain": {
"elevation_ft": 1275.4,
"local_relief_150m_ft": 429.8,
"slope_degrees": 23.59,
"aspect_degrees": 179.2,
"source": {
"agency": "USGS",
"product": "3DEP Bare Earth DEM Dynamic service 30 m raster export sample"
},
"confidence": 0.9
},
"soil": {
"mukey": "459841",
"musym": "PcB",
"mapunit_name": "Pajaro clay loam, overwash, 2 to 5 percent slopes",
"hydrologic_group": "C/D",
"drainage_class": "Somewhat poorly drained",
"source": {
"agency": "USDA NRCS",
"product": "SSURGO mapunit polygon centroid intersect with SDA mapunit attributes"
}
},
"vegetation": {
"canopy": {
"canopy_percent": 0,
"year": 2023,
"source": {
"agency": "USDA Forest Service",
"product": "NLCD Tree Canopy Cover 2023 raster export sample"
}
}
},
"narrative": {
"text": "0.77 acre parcel, with a 1952 primary structure, at 1275.4 ft elevation.",
"grounded_in": ["parcel", "building", "terrain", "risk.fire", "risk.flood"]
},
"embedding": {
"dim": 1536,
"model": "text-embedding-3-small",
"status": "metadata_only"
},
"sources": {
"parcel_boundaries": {
"agency": "County of Sonoma",
"source_file": "parcels.geojson"
},
"parcel_terrain_attributes": {
"agency": "USGS",
"source_file": "terrain.csv"
},
"soil_attributes": {
"agency": "USDA NRCS",
"source_file": "soil.csv"
},
"flood_hazard_zones": {
"agency": "FEMA",
"source_file": "flood_zones.geojson"
}
},
"field_sources": {
"parcel.apn": "parcel_boundaries",
"terrain.elevation_ft": "parcel_terrain_attributes",
"soil.mukey": "soil_attributes",
"risk_features.flood.fema_zone": "flood_hazard_zones",
"narrative.grounded_in": ["parcel_boundaries", "parcel_building_attributes", "parcel_terrain_attributes", "burn_perimeters", "flood_hazard_zones"]
}
}
Error Responses
Errors use JSON bodies with ok: false and a short error string.
HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer
{"ok":false,"error":"Missing bearer token."}
HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer
{"ok":false,"error":"Invalid API key."}
HTTP/1.1 400 Bad Request
{"ok":false,"error":"Provide an address query."}
HTTP/1.1 404 Not Found
{"ok":false,"error":"Parcel not found."}
HTTP/1.1 429 Too Many Requests
Retry-After: 60
{"ok":false,"error":"Too many requests. Try again later."}
Batch requests also return 400 when the body is empty or contains more than 100 total parcel IDs, APNs, and address queries.
Rate Limits
Sandbox access is intended for functional evaluation, integration tests, and response-shape validation. Coordinate before scripted load tests or bulk runs.
/v1/parcels:batch-enrich: up to 100 total lookups per request./v1/parcels/search: defaultlimitis 10; maximum returned matches is 25./api/waitlist: 8 submissions per IP per 10 minutes./api/checkout: 20 checkout starts per IP per 10 minutes./api/checkout/status: 60 checks per IP per 10 minutes./v1/usagereports request counts for the current API key.
Test Parcels
The examples below use the Sonoma release. Check GET /v1/datasets for current loaded releases and use their real dataset_id or county_fips for scoped APN lookup and address search. For MCP, use the approved releases returned by list_datasets.
| Parcel ID | APN | Address Query |
|---|---|---|
lm_ca_001-011-004 |
001-011-004 |
721 CLOVERDALE BLVD N |
lm_ca_028-030-009 |
028-030-009 |
3225 FRANZ VALLEY RD |
lm_ca_079-020-011 |
079-020-011 |
10275 LOCH HAVEN DR |
lm_ca_091-340-003-112542 |
091-340-003 |
1830 BOXHEART DR |
Some APNs have multiple county geometries. If a direct parcel ID misses or an APN has duplicates, retry with /v1/parcels/by-apn/:apn and inspect the returned parcel IDs.
Sandbox Access
To evaluate Lotmark, send the team a work email, company name, intended use case, expected test volume, and whether you need APN lookup, address search, batch enrichment, or QA reports. We will provision a sandbox bearer key and confirm the bundle loaded for your tests.
curl -s -X POST "https://lotmark.io/api/waitlist" -H "Content-Type: application/json" -d '{"email":"you@company.com","name":"Your Name","company":"Company","role":"proptech-ai","plan":"developer","message":"Please provision sandbox API access for APN lookup, address search, batch enrichment, and QA reports.","request_demo":false}'
After credentials are provisioned, start with /health, then run APN lookup and /v1/usage. Keep API keys out of client-side code and browser logs.