{"openapi":"3.1.0","info":{"title":"Geo & Environment Lookups API","version":"1.0.0","description":"NASA FIRMS fire hotspots, USGS earthquakes, NOAA solar times/position, US ACS demographics, and next GTFS scheduled arrivals from vendored official data or pure computation. Paid with x402 exact USDC on Base. No account is required.","contact":{"email":"support@brainiac.software"},"x-guidance":"BRAINIAC.software is a pay-per-call API for software agents. No account or API key is required.\nPayment uses x402 with exact USDC on Base (8453). Each paid resource accepts POST for the call; unpaid GET/HEAD return the same 402 payment challenge for discovery.\nHow to call an operation:\n1. POST JSON matching the requestBody. An unpaid POST (including empty body) returns 402 payment terms before body validation.\n2. Compare 402 payTo, asset, and network with /api/v1/catalog and /.well-known/x402 — not only with the 402 itself.\n3. Pay and retry with payment-signature. Invalid JSON/schema after payment-signature returns 400 and is not charged. Settlement (a charge) only on 2xx. payment-signature attached ≠ charged.\nIdempotency-Key: 64 hex chars from 32 random bytes. Reuse only for the same operation and body (replays stored response, including status=partial). A new key runs a fresh call.\nIdempotency after errors: unpaid 402 does not store the key. Post-signature 402/503 release it (retry same key). Pre-reserve schema 400 does not store it. Other post-signature responses (2xx/4xx/5xx) are stored: same key+body replays; different body → 409. Stored 4xx/5xx replays are not a second charge. Prefer a new key after fixing a 4xx; after 5xx reuse the same key only for the stored error.\nPost-signature 402/503 include prior-payment-attempt (nonce, settled false|unknown). A facilitator 502 is SETTLEMENT_UNKNOWN (stored under the Idempotency-Key; cross-instance replay needs the shared store; may already be charged) — check USDC authorizationState(payer, nonce) on Base before re-signing.\nSettlement signal: settled 2xx include payment-response. 4xx/5xx do not. Do not book a cost from payment-signature alone.\nCoverage billing: HTTP 200 with status complete, partial, or failed is charged at the full listed price. Retrying missing checks needs a new settled call. 4xx/5xx are not charged.\nmissing_items.reason: timeout/rate_limited → one delayed retry (new key); upstream_down → after recovery; not_supported → never.\nInvariants: any missing_items ⇒ not status complete; sources[] is provenance only (source, url, retrievedAt), never success/error keyed by check.\nFree lookup: GET /api/v1/results/{result_id} returns stored coverage JSON (404 RESULT_NOT_FOUND if unknown/expired; not a 402). Prior-Result-Id sets replaces_result_id.\nOutputs are prechecks/drafts for human review — not official determinations, legal advice, or certified filings."},"servers":[{"url":"https://www.brainiac.software"}],"paths":{"/api/v1/geo-environment/fire-hotspots-nearby":{"post":{"operationId":"list_nearby_nasa_firms_fire_hotspots","summary":"List nearby NASA FIRMS fire hotspots","description":"List MODIS C6.1 active-fire detections within a radius from the vendored 7-day FIRMS snapshot.","tags":["geo-environment"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"latitude":{"type":"number","minimum":-90,"maximum":90},"longitude":{"type":"number","minimum":-180,"maximum":180},"radiusKm":{"type":"number","minimum":0.1,"maximum":500},"from":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"to":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"minConfidence":{"type":"number","minimum":0,"maximum":100},"limit":{"default":100,"type":"integer","minimum":1,"maximum":500}},"required":["latitude","longitude","radiusKm"],"additionalProperties":false},"example":{"latitude":33.2613,"longitude":131.64961,"radiusKm":10}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":true,"description":"Fresh random 32-byte value encoded as 64 hexadecimal characters. Reuse unchanged only for retries of the same operation and request.","schema":{"type":"string","pattern":"^[0-9a-fA-F]{64}$"}}],"responses":{"200":{"description":"Illustrative endpoint-specific JSON response shape. For coverage operations, HTTP 200 is used for status complete, partial, and failed; all three settle and are charged at the full listed price. A settled 2xx includes a payment-response response header (facilitator settlement receipt; may include a transaction reference). Conditional fields depend on the result and data-source availability.","headers":{"payment-response":{"description":"Present on settled 2xx only. Facilitator settlement receipt for the x402 payment (not present on 4xx/5xx, which are not charged).","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"count":{"type":"number"},"detections":{"type":"array","items":{"type":"object","properties":{"latitude":{"type":"number"},"longitude":{"type":"number"},"distanceKm":{"type":"number"},"acquiredAt":{"type":"string"},"satellite":{"type":"string"},"confidence":{"type":"number"},"brightnessK":{"type":"number"},"brightT31K":{"type":"number"},"frpMw":{"type":"number"},"dayNight":{"type":"string"},"version":{"type":"string"}},"additionalProperties":true}},"window":{"type":"object","properties":{"from":{"type":"string"},"to":{"type":"string"}},"additionalProperties":true},"snapshotAt":{"type":"string"},"sources":{"type":"array","items":{"type":"object","properties":{"source":{"type":"string"},"url":{"type":"string"},"retrievedAt":{"type":"string"},"status":{"type":"string"}},"additionalProperties":true},"description":"Provenance only (source, url, retrievedAt). Not keyed by check id and does not carry success or error. A check in missing_items does not remove its upstream from sources[]; unavailability is only in missing_items (and unavailable findings)."},"limitations":{"type":"array","items":{"type":"string"}}},"additionalProperties":true},"example":{"count":1,"detections":[{"latitude":33.2613,"longitude":131.64961,"distanceKm":0,"acquiredAt":"2026-11-08T00:28:00Z","satellite":"Terra","confidence":0,"brightnessK":307.73,"brightT31K":289.01,"frpMw":15.28,"dayNight":"D","version":"6.1NRT"}],"window":{"from":"2026-11-08","to":"2026-11-15"},"snapshotAt":"2026-11-15","sources":[{"source":"NASA FIRMS MODIS C6.1 Global 7-day active fires","url":"https://firms.modaps.eosdis.nasa.gov/data/active_fire/modis-c6.1/csv/MODIS_C6_1_Global_7d.csv","retrievedAt":"2026-11-15","status":"ok"}],"limitations":["Detections are NASA FIRMS MODIS C6.1 active-fire hotspots in the vendored 7-day window, not a confirmation of wildfire …"]}}}},"400":{"description":"Invalid JSON or request schema. Not charged (no payment-response). If this 400 is returned before the Idempotency-Key is reserved, the key is not stored — fix the body and you may reuse the key. If an operation-path 400 was stored after a payment-signature was attached, the same key + same body replays it; the same key + a different body returns 409."},"402":{"description":"Payment required. The JSON body is the x402 PaymentRequired object. An unpaid 402 does not store the Idempotency-Key. A 402 after payment-signature releases the key and includes prior-payment-attempt (nonce, settled false|unknown). Not charged; no payment-response. Before re-signing after a post-signature 402, check USDC authorizationState(payer, nonce) on Base."},"409":{"description":"Idempotency conflict, in-progress payment, or expired result cache. Same key with a different body after a stored result returns conflict. Reusing the key cannot trigger a second charge. Not charged when settlement did not occur."},"413":{"description":"Request body exceeds the 24 MB limit. Not charged."},"500":{"description":"Operation failed before settlement, so no payment is taken (no payment-response). The error is stored: reuse the same Idempotency-Key and body to retrieve it without paying again. Use a new key for a fresh attempt with a new payment-signature."},"502":{"description":"Facilitator verify/settle transport failure (often timeout). After payment-signature this is returned as SETTLEMENT_UNKNOWN with prior-payment-attempt; the outcome is stored under the Idempotency-Key. With the shared store configured, other instances replay it instead of settling again; without it, each instance keeps its own memory. The authorization may already be settled on-chain — do not re-sign until USDC authorizationState(payer, nonce) on Base is false."},"503":{"description":"Payment or retry-safe result storage is unavailable; the operation is not run. Not charged; no payment-response. A 503 after payment-signature releases the Idempotency-Key and includes prior-payment-attempt."}},"x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.03"},"protocols":[{"x402":{"facilitator":"https://api.cdp.coinbase.com/platform/v2/x402"}}],"facilitator":"https://api.cdp.coinbase.com/platform/v2/x402"}}},"/api/v1/geo-environment/earthquake-query":{"post":{"operationId":"query_usgs_earthquakes_nearby","summary":"Query USGS earthquakes nearby","description":"Find earthquakes within a radius and time window from the vendored USGS all_month feed.","tags":["geo-environment"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"latitude":{"type":"number","minimum":-90,"maximum":90},"longitude":{"type":"number","minimum":-180,"maximum":180},"radiusKm":{"type":"number","minimum":1,"maximum":20000},"minMagnitude":{"type":"number"},"from":{"type":"string","minLength":10,"maxLength":40},"to":{"type":"string","minLength":10,"maxLength":40},"eventType":{"default":"earthquake","type":"string","minLength":1,"maxLength":40},"sort":{"default":"time","type":"string","enum":["time","magnitude"]},"limit":{"default":100,"type":"integer","minimum":1,"maximum":500}},"required":["latitude","longitude","radiusKm"],"additionalProperties":false},"example":{"latitude":32.3376,"longitude":93.7837,"radiusKm":100,"minMagnitude":4.5}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":true,"description":"Fresh random 32-byte value encoded as 64 hexadecimal characters. Reuse unchanged only for retries of the same operation and request.","schema":{"type":"string","pattern":"^[0-9a-fA-F]{64}$"}}],"responses":{"200":{"description":"Illustrative endpoint-specific JSON response shape. For coverage operations, HTTP 200 is used for status complete, partial, and failed; all three settle and are charged at the full listed price. A settled 2xx includes a payment-response response header (facilitator settlement receipt; may include a transaction reference). Conditional fields depend on the result and data-source availability.","headers":{"payment-response":{"description":"Present on settled 2xx only. Facilitator settlement receipt for the x402 payment (not present on 4xx/5xx, which are not charged).","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"count":{"type":"number"},"events":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"time":{"type":"string"},"latitude":{"type":"number"},"longitude":{"type":"number"},"depthKm":{"type":"number"},"magnitude":{"type":"number"},"magType":{"type":"string"},"place":{"type":"string"},"type":{"type":"string"},"status":{"type":"string"},"network":{"type":"string"},"distanceKm":{"type":"number"},"url":{"type":"string"}},"additionalProperties":true}},"window":{"type":"object","properties":{"from":{"type":"string"},"to":{"type":"string"}},"additionalProperties":true},"snapshotAt":{"type":"string"},"sources":{"type":"array","items":{"type":"object","properties":{"source":{"type":"string"},"url":{"type":"string"},"retrievedAt":{"type":"string"},"status":{"type":"string"}},"additionalProperties":true},"description":"Provenance only (source, url, retrievedAt). Not keyed by check id and does not carry success or error. A check in missing_items does not remove its upstream from sources[]; unavailability is only in missing_items (and unavailable findings)."},"limitations":{"type":"array","items":{"type":"string"}}},"additionalProperties":true},"example":{"count":1,"events":[{"id":"us6000u43g","time":"2026-10-22T14:33:40.289Z","latitude":32.3376,"longitude":93.7837,"depthKm":18,"magnitude":7,"magType":"mww","place":"189 km ENE of Nagqu, China","type":"earthquake","status":"reviewed","network":"us","distanceKm":0,"url":"https://earthquake.usgs.gov/earthquakes/eventpage/us6000u43g"}],"window":{"from":"2026-10-16T10:15:38.430Z","to":"2026-11-15T09:39:57.110Z"},"snapshotAt":"2026-11-15","sources":[{"source":"USGS Earthquake Hazards Program ComCat all_month CSV","url":"https://earthquake.usgs.gov/earthquakes/feed/v1.0/summary/all_month.csv","retrievedAt":"2026-11-15","status":"ok"}],"limitations":["Events come from the vendored USGS ComCat all_month feed; updated or deleted events reflect the snapshot only."]}}}},"400":{"description":"Invalid JSON or request schema. Not charged (no payment-response). If this 400 is returned before the Idempotency-Key is reserved, the key is not stored — fix the body and you may reuse the key. If an operation-path 400 was stored after a payment-signature was attached, the same key + same body replays it; the same key + a different body returns 409."},"402":{"description":"Payment required. The JSON body is the x402 PaymentRequired object. An unpaid 402 does not store the Idempotency-Key. A 402 after payment-signature releases the key and includes prior-payment-attempt (nonce, settled false|unknown). Not charged; no payment-response. Before re-signing after a post-signature 402, check USDC authorizationState(payer, nonce) on Base."},"409":{"description":"Idempotency conflict, in-progress payment, or expired result cache. Same key with a different body after a stored result returns conflict. Reusing the key cannot trigger a second charge. Not charged when settlement did not occur."},"413":{"description":"Request body exceeds the 24 MB limit. Not charged."},"500":{"description":"Operation failed before settlement, so no payment is taken (no payment-response). The error is stored: reuse the same Idempotency-Key and body to retrieve it without paying again. Use a new key for a fresh attempt with a new payment-signature."},"502":{"description":"Facilitator verify/settle transport failure (often timeout). After payment-signature this is returned as SETTLEMENT_UNKNOWN with prior-payment-attempt; the outcome is stored under the Idempotency-Key. With the shared store configured, other instances replay it instead of settling again; without it, each instance keeps its own memory. The authorization may already be settled on-chain — do not re-sign until USDC authorizationState(payer, nonce) on Base is false."},"503":{"description":"Payment or retry-safe result storage is unavailable; the operation is not run. Not charged; no payment-response. A 503 after payment-signature releases the Idempotency-Key and includes prior-payment-attempt."}},"x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.03"},"protocols":[{"x402":{"facilitator":"https://api.cdp.coinbase.com/platform/v2/x402"}}],"facilitator":"https://api.cdp.coinbase.com/platform/v2/x402"}}},"/api/v1/geo-environment/sun-times-position":{"post":{"operationId":"compute_sunrise_sunset_and_solar_position","summary":"Compute sunrise sunset and solar position","description":"Compute sunrise, solar noon, sunset, day length and solar elevation/azimuth with NOAA Solar Calculator equations.","tags":["geo-environment"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"latitude":{"type":"number","minimum":-90,"maximum":90},"longitude":{"type":"number","minimum":-180,"maximum":180},"date":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"instant":{"type":"string","minLength":10,"maxLength":40},"timeZone":{"default":"UTC","type":"string","minLength":1,"maxLength":80}},"required":["latitude","longitude"],"additionalProperties":false},"example":{"latitude":51.5074,"longitude":-0.1278,"date":"2026-11-14","instant":"2026-11-14T12:00:00Z"}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":true,"description":"Fresh random 32-byte value encoded as 64 hexadecimal characters. Reuse unchanged only for retries of the same operation and request.","schema":{"type":"string","pattern":"^[0-9a-fA-F]{64}$"}}],"responses":{"200":{"description":"Illustrative endpoint-specific JSON response shape. For coverage operations, HTTP 200 is used for status complete, partial, and failed; all three settle and are charged at the full listed price. A settled 2xx includes a payment-response response header (facilitator settlement receipt; may include a transaction reference). Conditional fields depend on the result and data-source availability.","headers":{"payment-response":{"description":"Present on settled 2xx only. Facilitator settlement receipt for the x402 payment (not present on 4xx/5xx, which are not charged).","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"date":{"type":"string"},"sunrise":{"type":"string"},"solarNoon":{"type":"string"},"sunset":{"type":"string"},"dayLengthMinutes":{"type":"number"},"polar":{"type":"null"},"position":{"type":"object","properties":{"elevationDeg":{"type":"number"},"azimuthDeg":{"type":"number"},"declinationDeg":{"type":"number"}},"additionalProperties":true},"accuracy":{"type":"string"},"method":{"type":"string"},"sources":{"type":"array","items":{"type":"object","properties":{"source":{"type":"string"},"url":{"type":"string"},"retrievedAt":{"type":"string"},"status":{"type":"string"}},"additionalProperties":true},"description":"Provenance only (source, url, retrievedAt). Not keyed by check id and does not carry success or error. A check in missing_items does not remove its upstream from sources[]; unavailability is only in missing_items (and unavailable findings)."},"limitations":{"type":"array","items":{"type":"string"}}},"additionalProperties":true},"example":{"date":"2026-11-14","sunrise":"2026-11-14T07:17:02Z","solarNoon":"2026-11-14T11:44:54Z","sunset":"2026-11-14T16:12:46Z","dayLengthMinutes":535.7,"polar":null,"position":{"elevationDeg":20.12,"azimuthDeg":183.82,"declinationDeg":-18.299},"accuracy":"±1 min within ±72° latitude, ±10 min outside","method":"NOAA Solar Calculator equations (Meeus); geometric elevation without refraction correction","sources":[{"source":"NOAA Global Monitoring Laboratory Solar Calculator","url":"https://gml.noaa.gov/grad/solcalc/calcdetails.html","retrievedAt":"2026-11-14","status":"ok"}],"limitations":["Times are computed, not observed. Polar day/night returns null sunrise/sunset."]}}}},"400":{"description":"Invalid JSON or request schema. Not charged (no payment-response). If this 400 is returned before the Idempotency-Key is reserved, the key is not stored — fix the body and you may reuse the key. If an operation-path 400 was stored after a payment-signature was attached, the same key + same body replays it; the same key + a different body returns 409."},"402":{"description":"Payment required. The JSON body is the x402 PaymentRequired object. An unpaid 402 does not store the Idempotency-Key. A 402 after payment-signature releases the key and includes prior-payment-attempt (nonce, settled false|unknown). Not charged; no payment-response. Before re-signing after a post-signature 402, check USDC authorizationState(payer, nonce) on Base."},"409":{"description":"Idempotency conflict, in-progress payment, or expired result cache. Same key with a different body after a stored result returns conflict. Reusing the key cannot trigger a second charge. Not charged when settlement did not occur."},"413":{"description":"Request body exceeds the 24 MB limit. Not charged."},"500":{"description":"Operation failed before settlement, so no payment is taken (no payment-response). The error is stored: reuse the same Idempotency-Key and body to retrieve it without paying again. Use a new key for a fresh attempt with a new payment-signature."},"502":{"description":"Facilitator verify/settle transport failure (often timeout). After payment-signature this is returned as SETTLEMENT_UNKNOWN with prior-payment-attempt; the outcome is stored under the Idempotency-Key. With the shared store configured, other instances replay it instead of settling again; without it, each instance keeps its own memory. The authorization may already be settled on-chain — do not re-sign until USDC authorizationState(payer, nonce) on Base is false."},"503":{"description":"Payment or retry-safe result storage is unavailable; the operation is not run. Not charged; no payment-response. A 503 after payment-signature releases the Idempotency-Key and includes prior-payment-attempt."}},"x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.01"},"protocols":[{"x402":{"facilitator":"https://api.cdp.coinbase.com/platform/v2/x402"}}],"facilitator":"https://api.cdp.coinbase.com/platform/v2/x402"}}},"/api/v1/geo-environment/us-acs-demographics":{"post":{"operationId":"look_up_us_acs_demographics","summary":"Look up US ACS demographics","description":"Return selected ACS 2020–2024 5-year estimates and margins of error for a US state, county or ZCTA.","tags":["geo-environment"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"geography":{"type":"string","enum":["state","county","zcta"]},"code":{"type":"string","minLength":1,"maxLength":10}},"required":["geography","code"],"additionalProperties":false},"example":{"geography":"zcta","code":"10001"}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":true,"description":"Fresh random 32-byte value encoded as 64 hexadecimal characters. Reuse unchanged only for retries of the same operation and request.","schema":{"type":"string","pattern":"^[0-9a-fA-F]{64}$"}}],"responses":{"200":{"description":"Illustrative endpoint-specific JSON response shape. For coverage operations, HTTP 200 is used for status complete, partial, and failed; all three settle and are charged at the full listed price. A settled 2xx includes a payment-response response header (facilitator settlement receipt; may include a transaction reference). Conditional fields depend on the result and data-source availability.","headers":{"payment-response":{"description":"Present on settled 2xx only. Facilitator settlement receipt for the x402 payment (not present on 4xx/5xx, which are not charged).","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"geoId":{"type":"string"},"geography":{"type":"string"},"vintage":{"type":"string"},"values":{"type":"object","properties":{"totalPopulation":{"type":"object","properties":{"estimate":{"type":"number"},"moe":{"type":"number"}},"additionalProperties":true},"medianAge":{"type":"object","properties":{"total":{"type":"object","properties":{"estimate":{"type":"number"},"moe":{"type":"number"}},"additionalProperties":true},"male":{"type":"object","properties":{"estimate":{"type":"number"},"moe":{"type":"number"}},"additionalProperties":true},"female":{"type":"object","properties":{"estimate":{"type":"number"},"moe":{"type":"number"}},"additionalProperties":true}},"additionalProperties":true},"medianHouseholdIncome":{"type":"object","properties":{"estimate":{"type":"number"},"moe":{"type":"number"}},"additionalProperties":true},"medianGrossRent":{"type":"object","properties":{"estimate":{"type":"number"},"moe":{"type":"number"}},"additionalProperties":true},"medianHomeValue":{"type":"object","properties":{"estimate":{"type":"number"},"moe":{"type":"number"}},"additionalProperties":true}},"additionalProperties":true},"sources":{"type":"array","items":{"type":"object","properties":{"source":{"type":"string"},"url":{"type":"string"},"retrievedAt":{"type":"string"},"status":{"type":"string"}},"additionalProperties":true},"description":"Provenance only (source, url, retrievedAt). Not keyed by check id and does not carry success or error. A check in missing_items does not remove its upstream from sources[]; unavailability is only in missing_items (and unavailable findings)."},"limitations":{"type":"array","items":{"type":"string"}}},"additionalProperties":true},"example":{"geoId":"860Z200US10001","geography":"zcta","vintage":"ACS 2020-2024 5-year","values":{"totalPopulation":{"estimate":30511,"moe":1797},"medianAge":{"total":{"estimate":35.8,"moe":1.1},"male":{"estimate":36.3,"moe":2},"female":{"estimate":35.2,"moe":1.9}},"medianHouseholdIncome":{"estimate":129852,"moe":25244},"medianGrossRent":{"estimate":3361,"moe":268},"medianHomeValue":{"estimate":561100,"moe":361292}},"sources":[{"source":"ACS 2020–2024 5-year table-based Summary File (B01003, B01002, B19013, B25064, B25077)","url":"https://www2.census.gov/programs-surveys/acs/summary_file/2024/table-based-SF/data/5YRData/","retrievedAt":"2026-11-15","status":"ok"}],"limitations":["Vendored subset covers states, counties, and ZCTAs only; tracts and places are not included."]}}}},"400":{"description":"Invalid JSON or request schema. Not charged (no payment-response). If this 400 is returned before the Idempotency-Key is reserved, the key is not stored — fix the body and you may reuse the key. If an operation-path 400 was stored after a payment-signature was attached, the same key + same body replays it; the same key + a different body returns 409."},"402":{"description":"Payment required. The JSON body is the x402 PaymentRequired object. An unpaid 402 does not store the Idempotency-Key. A 402 after payment-signature releases the key and includes prior-payment-attempt (nonce, settled false|unknown). Not charged; no payment-response. Before re-signing after a post-signature 402, check USDC authorizationState(payer, nonce) on Base."},"409":{"description":"Idempotency conflict, in-progress payment, or expired result cache. Same key with a different body after a stored result returns conflict. Reusing the key cannot trigger a second charge. Not charged when settlement did not occur."},"413":{"description":"Request body exceeds the 24 MB limit. Not charged."},"500":{"description":"Operation failed before settlement, so no payment is taken (no payment-response). The error is stored: reuse the same Idempotency-Key and body to retrieve it without paying again. Use a new key for a fresh attempt with a new payment-signature."},"502":{"description":"Facilitator verify/settle transport failure (often timeout). After payment-signature this is returned as SETTLEMENT_UNKNOWN with prior-payment-attempt; the outcome is stored under the Idempotency-Key. With the shared store configured, other instances replay it instead of settling again; without it, each instance keeps its own memory. The authorization may already be settled on-chain — do not re-sign until USDC authorizationState(payer, nonce) on Base is false."},"503":{"description":"Payment or retry-safe result storage is unavailable; the operation is not run. Not charged; no payment-response. A 503 after payment-signature releases the Idempotency-Key and includes prior-payment-attempt."}},"x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.03"},"protocols":[{"x402":{"facilitator":"https://api.cdp.coinbase.com/platform/v2/x402"}}],"facilitator":"https://api.cdp.coinbase.com/platform/v2/x402"}}},"/api/v1/geo-environment/gtfs-next-arrivals":{"post":{"operationId":"compute_next_gtfs_scheduled_arrivals","summary":"Compute next GTFS scheduled arrivals","description":"Compute next scheduled arrivals at a stop from a caller-supplied static GTFS zip. No feeds are fetched.","tags":["geo-environment"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"gtfsZipBase64":{"type":"string","minLength":16,"maxLength":14000000},"stopId":{"type":"string","minLength":1,"maxLength":120},"at":{"type":"string","minLength":10,"maxLength":40},"limit":{"default":5,"type":"integer","minimum":1,"maximum":50},"includeChildStops":{"default":false,"type":"boolean"}},"required":["gtfsZipBase64","stopId","at"],"additionalProperties":false},"example":{"gtfsZipBase64":"UEsDBBQAAAAIALFSb127LvAxTgAAAF0AAAAKAAAAYWdlbmN5LnR4dEtMT81LrozPTNFJhLDyEnNTYezSohwYsyQzN7UqPy+Vy1HHJTU3XyejpKSg2EpfP7UiMbcgJ1UvOT9XxzE3tSgzOVHfL7U8PjK/KJsLAFBLAwQUAAAACACxUm9dagz5Sx0AAAAfAAAACQAAAHN0b3BzLnR4dCsuyS+Iz0zRKQbReYm5qVzBhjouqbn5CsFAES4AUEsDBBQAAAAIALFSb10nN74dLwAAADgAAAAKAAAAcm91dGVzLnR4dCvKLy1Jjc9M0UlMT81LrgSxisBCxRn5RSXxeYm5qVCBksqCVK4gQx1HHUMdYy4AUEsDBBQAAAAIALFSb11FdLkkOAAAAEwAAAAJAAAAdHJpcHMudHh0K8ovLUmNz0zRKU4tKstMBjNLijIL4HRGamJKcWZ6HleQoU64i06IoY5LfnleCRDDRIx0QgvAfABQSwMEFAAAAAgAsVJvXUTDtAROAAAAbgAAAA4AAABzdG9wX3RpbWVzLnR4dCspyiyIz0zRSSwqyixLzIkvycxN1UlJLUgsKiktSoVwi0vywWrAdHFqYWlqXnIqV4ihjoGFlYEBECEYwYY6hlwhRjpGplaGYAE4AywDAFBLAwQUAAAACACxUm9ddvAAwFkAAAB7AAAADAAAAGNhbGVuZGFyLnR4dD3LMQqAMAyF4b1nydBU8ATewbEUE7GDFdJU8fbaCPIP71teZTnzwjET7EehdIM2rn0vpvJJtyaGVXKfmrSJodmjahKNlJSBCxncPAH++bfgw+jRowHDgO4BUEsDBBQAAAAIALFSb13OfSiGLwAAAC0AAAASAAAAY2FsZW5kYXJfZGF0ZXMudHh0K04tKstMTo3PTNFJSSxJ1UmtSE4tKMnMz4svqSxI5Qp30TEyMDIzNDQy0zHiAgBQSwECFAMUAAAACACxUm9duy7wMU4AAABdAAAACgAAAAAAAAAAAAAApIEAAAAAYWdlbmN5LnR4dFBLAQIUAxQAAAAIALFSb11qDPlLHQAAAB8AAAAJAAAAAAAAAAAAAACkgXYAAABzdG9wcy50eHRQSwECFAMUAAAACACxUm9dJze+HS8AAAA4AAAACgAAAAAAAAAAAAAApIG6AAAAcm91dGVzLnR4dFBLAQIUAxQAAAAIALFSb11FdLkkOAAAAEwAAAAJAAAAAAAAAAAAAACkgREBAAB0cmlwcy50eHRQSwECFAMUAAAACACxUm9dRMO0BE4AAABuAAAADgAAAAAAAAAAAAAApIFwAQAAc3RvcF90aW1lcy50eHRQSwECFAMUAAAACACxUm9ddvAAwFkAAAB7AAAADAAAAAAAAAAAAAAApIHqAQAAY2FsZW5kYXIudHh0UEsBAhQDFAAAAAgAsVJvXc59KIYvAAAALQAAABIAAAAAAAAAAAAAAKSBbQIAAGNhbGVuZGFyX2RhdGVzLnR4dFBLBQYAAAAABwAHAJQBAADMAgAAAAA=","stopId":"S1","at":"2026-11-25T23:30:00-05:00","limit":2}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":true,"description":"Fresh random 32-byte value encoded as 64 hexadecimal characters. Reuse unchanged only for retries of the same operation and request.","schema":{"type":"string","pattern":"^[0-9a-fA-F]{64}$"}}],"responses":{"200":{"description":"Illustrative endpoint-specific JSON response shape. For coverage operations, HTTP 200 is used for status complete, partial, and failed; all three settle and are charged at the full listed price. A settled 2xx includes a payment-response response header (facilitator settlement receipt; may include a transaction reference). Conditional fields depend on the result and data-source availability.","headers":{"payment-response":{"description":"Present on settled 2xx only. Facilitator settlement receipt for the x402 payment (not present on 4xx/5xx, which are not charged).","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"stop":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"additionalProperties":true},"timeZone":{"type":"string"},"arrivals":{"type":"array","items":{"type":"object","properties":{"tripId":{"type":"string"},"routeId":{"type":"string"},"routeShortName":{"type":"string"},"headsign":{"type":"string"},"serviceDate":{"type":"string"},"scheduledArrival":{"type":"string"},"stopSequence":{"type":"number"}},"additionalProperties":true}},"warnings":{"type":"array","items":{}},"sources":{"type":"array","items":{"type":"object","properties":{"source":{"type":"string"},"url":{"type":"string"},"retrievedAt":{"type":"string"},"status":{"type":"string"}},"additionalProperties":true},"description":"Provenance only (source, url, retrievedAt). Not keyed by check id and does not carry success or error. A check in missing_items does not remove its upstream from sources[]; unavailability is only in missing_items (and unavailable findings)."},"limitations":{"type":"array","items":{"type":"string"}}},"additionalProperties":true},"example":{"stop":{"id":"S1","name":"Demo Stop"},"timeZone":"America/New_York","arrivals":[{"tripId":"T2","routeId":"R1","routeShortName":"1","headsign":"Uptown","serviceDate":"2026-11-25","scheduledArrival":"2026-11-26T01:10:00-05:00","stopSequence":1},{"tripId":"T1","routeId":"R1","routeShortName":"1","headsign":"Downtown","serviceDate":"2026-11-27","scheduledArrival":"2026-11-27T08:00:00-05:00","stopSequence":1}],"warnings":[],"sources":[{"source":"Caller-supplied GTFS Schedule feed (static)","url":"https://gtfs.org/documentation/schedule/reference/","retrievedAt":"2026-11-25","status":"ok"}],"limitations":["Pure computation on the uploaded static GTFS zip; no realtime trip updates are used."]}}}},"400":{"description":"Invalid JSON or request schema. Not charged (no payment-response). If this 400 is returned before the Idempotency-Key is reserved, the key is not stored — fix the body and you may reuse the key. If an operation-path 400 was stored after a payment-signature was attached, the same key + same body replays it; the same key + a different body returns 409."},"402":{"description":"Payment required. The JSON body is the x402 PaymentRequired object. An unpaid 402 does not store the Idempotency-Key. A 402 after payment-signature releases the key and includes prior-payment-attempt (nonce, settled false|unknown). Not charged; no payment-response. Before re-signing after a post-signature 402, check USDC authorizationState(payer, nonce) on Base."},"409":{"description":"Idempotency conflict, in-progress payment, or expired result cache. Same key with a different body after a stored result returns conflict. Reusing the key cannot trigger a second charge. Not charged when settlement did not occur."},"413":{"description":"Request body exceeds the 24 MB limit. Not charged."},"500":{"description":"Operation failed before settlement, so no payment is taken (no payment-response). The error is stored: reuse the same Idempotency-Key and body to retrieve it without paying again. Use a new key for a fresh attempt with a new payment-signature."},"502":{"description":"Facilitator verify/settle transport failure (often timeout). After payment-signature this is returned as SETTLEMENT_UNKNOWN with prior-payment-attempt; the outcome is stored under the Idempotency-Key. With the shared store configured, other instances replay it instead of settling again; without it, each instance keeps its own memory. The authorization may already be settled on-chain — do not re-sign until USDC authorizationState(payer, nonce) on Base is false."},"503":{"description":"Payment or retry-safe result storage is unavailable; the operation is not run. Not charged; no payment-response. A 503 after payment-signature releases the Idempotency-Key and includes prior-payment-attempt."}},"x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.04"},"protocols":[{"x402":{"facilitator":"https://api.cdp.coinbase.com/platform/v2/x402"}}],"facilitator":"https://api.cdp.coinbase.com/platform/v2/x402"}}}},"components":{"schemas":{"ApiError":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}}}}}}}}