---
title: "Compute Endpoint"
method: POST
path: "/v1/proximity"
tags: ["Proximity"]
---

# Compute Endpoint

`POST /v1/proximity`

## Request

- Base URL: `https://api.mireye.com`
- URL: `https://api.mireye.com/v1/proximity`
- Auth: none declared
- TypeScript: <https://skmtc.dev/mireye/apis/mireye-earth/docs/v1/proximity/post.ts> (a function with typed inputs; its response is checked against the schema)

## Request body

- union
  - DistanceOp: N origins x M destinations, driving or straightline.
    - `destinations` string[], required
    - `max_cost_usd` string, nullable: Maximum USD to reserve for this request. Defaults to $10; set an explicit decimal string to authorize a different ceiling. Unused reservation is released; only successful driving calculations are charged.
    - `mode` 'driving' | 'straightline'
    - `op` 'distance', required
    - `origins` string[], required
    - `units` 'miles' | 'km': Reserved for a future single-unit rendering. `Leg` always returns BOTH distance_miles and distance_km regardless of this value -- no behavior currently depends on it.
  - NearestOp: Top-N candidates from a curated set, ranked by driving duration (or straightline distance in ``straightline`` mode).
    - `filters` object, nullable: Set-specific filters. Curated sets: scalar values as documented for each set (unchanged). "@places": an object with at least one of `brand_wikidata` (Wikidata item IDs, "Q" followed by digits), `brand_name` (exact name, case-insensitive: matches the record's brand name, or its place name when the record has no brand name), `category` (place-data taxonomy tokens, lowercase snake_case, a token includes its sub-categories), plus optional `min_confidence` (0 to 1, default 0.5). Each of the three selectors takes one string or a list of up to 20. `brand_wikidata` and `brand_name` combine with OR: a record matching either is returned, and `attributes.matched_by` says which matched. Place-name matches find stores the data left without a brand tag, but include more stale and non-store records. `category` ANDs with the brand keys when both are given, which often drops real stores because chains are tagged inconsistently, so omit `category` for brand lookups. Wikidata IDs are present on only a small share of chain records (measured 2 to 20 percent), so always pass `brand_name` alongside `brand_wikidata`. A wrong but valid-looking Wikidata ID or a mistyped category token returns nothing, indistinguishable from none found. The normalized filters are echoed in `applied_filters`.
    - `max_cost_usd` string, nullable: Maximum USD to reserve for this request. Defaults to $10; set an explicit decimal string to authorize a different ceiling. Unused reservation is released; only successful driving calculations are charged.
    - `mode` 'driving' | 'straightline'
    - `n` integer
    - `op` 'nearest', required
    - `origin` string, required
    - `radius_m` number, nullable: "@places" only. Search radius in meters, measured as straight-line (geodesic) distance from the origin; maximum 50,000, default 50,000 for candidates, required when `return` is "count". It bounds which records are considered, in every mode: it is not a drive time or driving distance, and in driving mode candidates inside the circle are then ranked by typical-traffic duration. Records outside the radius are never returned or counted; none found inside it is unknown, not absent. Rejected for curated sets.
    - `return` 'candidates' | 'count': "candidates" (default): the nearest `n` place records as `candidates`, ranked by driving duration (driving mode) or straight-line distance (straightline mode), after merging duplicates (same brand or name within 100 m). "count" ("@places" only, requires `radius_m`): returns `counts` with how many deduplicated records match `filters` within `radius_m`; it ignores `n` and `mode`, never routes, and is free. Read `count` together with `count_raw_records` and `truncated`: counts are deduplicated estimates of place records in the data, not official store counts. For a count per brand, make one call per brand.
    - `set` string, required: Which places to rank. A curated set ref ("@airports", "@substations", and the other documented sets) or "@places": a live query of place records from open data, by brand and/or category, selected through `filters` (required with "@places"). "@places" covers the US only and returns place RECORDS from conflated open data, not verified open stores; each candidate's `attributes.matched_by` says how it matched, and the response `notes` carry the coverage caveats. An empty "@places" result means no matching record was found, which is unknown, not proof that no such place exists. "@places" results were validated only for four grocery brands in two metros; brand and category coverage anywhere else is unmeasured.
  - ScreenOp: Filter origins by driving-duration proximity to ANY of up to 10 anchors.
    - `anchors` string[], required
    - `max_cost_usd` string, nullable: Maximum USD to reserve for this request. Defaults to $10; set an explicit decimal string to authorize a different ceiling. Unused reservation is released; only successful driving calculations are charged.
    - `max_minutes` integer, required
    - `min_minutes` integer, nullable
    - `op` 'screen', required
    - `origins` string[], required
  - LaborShedOp: Civilian labor force + population within a driving-minutes shed of one origin.
    - `estimate` boolean: Price this shed without running or paying for it. The tract prefilter that determines the price is free, so the estimate is a maximum, before failed routes are excluded. Returns a LaborShedEstimate; no driving matrix is called and no money is charged.
    - `include` string[]: Optional extra blocks. ["demographics"] adds ACS 5-year age, household, tenure, home-value and income totals summed over the SAME reachable tracts. Free: it reuses the shed's tract set and changes neither the price nor the other fields.
    - `max_cost_usd` string, nullable: Maximum USD to reserve for this request. Defaults to $10; set an explicit decimal string to authorize a different ceiling. Unused reservation is released; only successful driving calculations are charged.
    - `minutes` integer, required
    - `op` 'labor_shed', required
    - `origin` string, required

## Response `200`

Successful Response

- unknown

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/mireye/apis/mireye-earth.md) - [All operations](https://skmtc.dev/mireye/apis/mireye-earth/llms.txt) - [OpenAPI document](https://skmtc.dev/mireye/apis/mireye-earth/revisions/d8410ba83654?raw)