Fetch the same facts for several locations
fetch_batchGet the same preset and/or fields for several US locations in one synchronous call: the results come back in this response. Size: up to the plan's batch size (10 on Free, 100 on paid plans); fetch_location is the single-place form. More places than the batch size (up to 2000), or work that should not hold the call open, fit start_run with kind=batch, which is asynchronous: it returns a run id at once and get_run pages the results, at the same cost per location. Output: results index-aligned with locations, each with its own ok flag and either fields or an error, plus lookups_charged. One bad location does not fail the others. Cost: 1 lookup per location per started block of 50 delivered fields; locations with no data are free. Places not requested before are fetched live and can take a few seconds each. Behavior: read-only (no side effects); needs an API key or OAuth; each call counts toward the per-minute request limit (Free 10, Starter 60, Pro 300); one call is one request. Places run max_concurrent_locations at a time (Free 1, Starter 4, Pro 8), each waiting up to max_wait_s for slow sources; a place that waits over 20 s for a slot returns error busy (retryable). Lookups count toward the daily cap (Free 200, Starter 5000, Pro 25000). A repeat with the same idempotency_key within 24 h is free. Errors: whole-call errors as fetch_location (preset_unknown, fields_unknown, fields_too_many, no_fields_requested) and batch_too_large above the plan's batch size. Plan limits return rate_limited (with retry_after_s), daily_cap_reached or quota_exhausted.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| detail | No | compact (default): value, unit, status, source and confidence per field. full: the complete record per field, adding license, attribution, vintage and notes. Same cost. | compact |
| fields | No | Exact, case-sensitive field names from list_presets or search_fields (e.g. ['nfhl_flood_zone', 'elevation']). Combined with preset when both are given; up to 50 names that are not already in the preset. Unknown names fail the whole call with fields_unknown. | |
| preset | No | Exact preset name from list_presets (e.g. 'flood_risk', 'terrain', 'solar_siting'). Its fields are added to fields; large presets cost more than 1 lookup (1 per 50 delivered fields). | |
| locations | Yes | 1 to 100 places (capped by the plan's batch size), each an object with lat+lng or address, exactly one of the two. | |
| max_wait_s | No | Seconds to wait for slow live sources before returning those fields as failed; default 10 s, capped at 15 s on Free and 30 s on paid plans. Optional. | |
| idempotency_key | No | Optional 8-128 characters of letters, digits, _ or -. A retry with the same key and arguments within 24 h returns the stored result at no charge. |