POST /v1/fetch/batch

cURL

curl --request POST \
  --url https://api.example.com/v1/fetch/batch \
  --header 'Content-Type: application/json' \
  --data '
{
  "locations": [
    {
      "lat": 123,
      "lng": 123,
      "address": "<string>"
    }
  ],
  "fields": [
    "<string>"
  ]
}
'

The same field fetch for up to 25 locations in one request.

cURL

curl --request POST \
  --url https://api.example.com/v1/fetch/batch \
  --header 'Content-Type: application/json' \
  --data '
{
  "locations": [
    {
      "lat": 123,
      "lng": 123,
      "address": "<string>"
    }
  ],
  "fields": [
    "<string>"
  ]
}
'

​ When to use this

​ Request

curl -s https://api.mireye.com/v1/fetch/batch \
  -H "Authorization: Bearer $MIREYE_API_TOKEN" \
  -H 'content-type: application/json' \
  -d '{
    "locations": [
      {"lat": 29.7604, "lng": -95.3698},
      {"address": "350 5th Ave, New York, NY 10118"},
      {"lat": 39.7392, "lng": -104.9903}
    ],
    "fields": ["elevation", "coast_distance_m"]
  }' | jq

​ Response

{
  "fetched_at": "2026-07-27T09:00:00+00:00",
  "results": [
    {"index": 0, "ok": true, "lat": 29.7604, "lng": -95.3698,
     "fetched_at": "…", "fields": {"…": "…"}, "partial_failures": [],
     "resolved_location": {"lat": 29.7604, "lng": -95.3698, "source": "coordinate"}},
    {"index": 1, "ok": true, "lat": 40.748377, "lng": -73.984854,
     "fetched_at": "…", "fields": {"…": "…"}, "partial_failures": [],
     "geocode": {"accuracy_type": "rooftop", "…": "…"},
     "resolved_location": {"lat": 40.748377, "lng": -73.984854, "source": "address"}},
    {"index": 2, "ok": false,
     "error": {"error": "coord_out_of_bounds", "message": "…", "retryable": false}}
  ]
}

• Results are index-aligned with the request. results[i] answers locations[i], always, and carries index explicitly so a filtered or logged entry stays attributable.
• Each ok: true entry is a /v1/fetch response body. Same fields shape, same tri-state field status, same partial_failures, same geocode echo when the location was an address. A client that parses the single endpoint parses the batch with no new code.
• A location’s failure is an entry, never an HTTP failure. Location #7’s bad address cannot cost you the other 24 results: it becomes {"ok": false, "error": {…}} with the same error object (error, message, retryable) the single endpoint would have returned for that location — one error-handling code path for both endpoints.

​ Two levels of partial failure

• Entry-level (ok: false): the location itself failed — the address didn’t geocode, the coordinate is outside the US envelope, or the worker shed the location at capacity (fetch_busy, retryable).
• Field-level (partial_failures inside an ok: true entry): the location was fine, but individual fields failed upstream — identical semantics to /v1/fetch.

​ Limits

• 25 locations maximum per request (422 above it).
• The /v1/fetch field rules apply unchanged: 50 explicit fields max, presets exempt.
• Locations are processed 4 at a time inside the batch, and every location counts against the same per-worker admission gate as a single /v1/fetch — a batch is 25 requests’ worth of work and is metered as such, not smuggled under one admission slot. A location shed at capacity returns as an ok: false fetch_busy entry (retryable) rather than failing the batch.
• Worst-case latency ≈ 90 s (every location cold, every source at its budget). Typical is far lower, but set your client timeout to 120 s+, same guidance as /v1/ask.
• Addresses bill one geocode lookup each (cache-served repeats are free, 30-day TTL), and metered sources (e.g. parcel lookups) bill per location — a 25-location batch with a parcel field is 25 metered calls.
• Batch is REST-only for now: the MCP mireye_fetch tool stays single-location (agents iterate naturally), and MCP hosts impose their own tool-response size limits a 25-location payload would fight.

N locations, one field selection.

The field selection is deliberately batch-wide, not per-location: the batch exists for "the same screen over a list of candidate properties", and per-location field lists would make the response shape unpredictable for exactly the clients (agents, spreadsheets) the batch serves.

Show child attributes

Successful Response