> ## Documentation Index
> Fetch the complete documentation index at: https://syncupai-preview-poi-statuses-api.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# PlaceMatch

> This guide covers Reprompt's place matching API

## What is place matching?

Reprompt’s place matching conflates an input place against one or more sources (e.g., Reprompt, Overture, Foursquare, or your own data). The engine combines traditional similarity (name, location, category) with LLM verification to produce high-confidence matches.

* Output format: GeoJSON `FeatureCollection`
* Each `Feature.properties` includes:
  * **`source`**: where the match came from
  * **`confidence_score`**: overall confidence (0–1)
  * **`is_match`**: boolean match flag
  * **`match_explanation`**: optional human-readable explanation
  * Optional per-dimension scores/weights (name/location/category)

## Input modes and constraints

* **Coordinates-only**
  * Provide `latitude` and `longitude`.
  * Best when device or map interactions are available.
  * The engine applies geographic proximity and contextual cues.

* **Name + Address (+ optional coordinates)**
  * Provide `name` and `address`; coordinates improve precision.
  * Address should include postal code when possible for maximal accuracy.

* **Name-only**
  * Not supported without either coordinates or a full address; such requests will return `501 Not Implemented`.

Validation requirements:

* Provide at least a name OR coordinates.
* If `address` is provided, `name` is required.
* Provide both `latitude` and `longitude` together (no partial coordinates).
* BYOD candidates (below) are only valid when `match_sources` includes `byod`.

## Sources and configuration

* **`match_sources`**: choose one or more of `reprompt`, `overture`, `foursquare`, `byod`.
* **`max_matches`**: maximum results per source (maps to the engine’s `k`).
* **`radius`**: search radius in meters. Returned in metadata; the engine may use its own internal heuristics.

<Note>
  Per-source results are not merged (`merge_matches = false`). Evaluate per-feature `source` when reconciling across providers.
</Note>

## Bring Your Own Data (BYOD)

Include your own candidate places to match against.

* Enable by adding `"byod"` to `match_sources`.
* Provide up to 50 `match_byod_candidates` with any combination of:
  * `name` (recommended),
  * `address`,
  * `latitude` + `longitude` (preferred for strong results).
* Output features will include `source: "byod"` when your candidates match.

## Error handling and resiliency

You may encounter:

* **Validation errors (400/422)**: input shape issues (e.g., partial coordinates, address without name).
* **Not implemented (501)**: name-only without either coordinates or a full address/postal code.
* **Upstream/network errors (502)**: external matching service unavailable.
* **Internal errors (500)**: unexpected server conditions.

Recommended client behavior:

* Treat 4xx as fixable input errors; surface to calling service with actionable messages.
* Backoff and retry 5xx with jitter. Log correlation IDs if available.
* On empty `features`, avoid repeated immediate retries; enqueue for alternate workflows or human review.

## Example requests

Coordinates-only (Foursquare + Overture):

```json theme={null}
{
  "place": { "latitude": 40.7829, "longitude": -73.9654 },
  "match_sources": ["foursquare", "overture"],
  "max_matches": 3
}
```

Name+Address (+coords) (Reprompt + Overture):

```json theme={null}
{
  "place": {
    "name": "Starbucks",
    "address": "1585 Broadway, New York, NY 10036",
    "latitude": 40.7614327,
    "longitude": -73.9776216
  },
  "match_sources": ["reprompt", "overture"],
  "max_matches": 3
}
```

BYOD candidates:

```json theme={null}
{
  "place": { "latitude": 37.7749, "longitude": -122.4194 },
  "match_sources": ["byod"],
  "match_byod_candidates": [
    { "name": "Blue Bottle Coffee", "latitude": 37.7750, "longitude": -122.4195 },
    { "name": "Ritual Coffee Roasters", "latitude": 37.7748, "longitude": -122.4193 }
  ],
  "radius": 100,
  "max_matches": 3
}
```

### Using results effectively

* Prefer the top feature by `confidence_score` across all returned features.
* Auto-link to the top feature when `confidence_score >= 0.90`.
* For `0.80–0.90`, auto-link when corroborated by external signals (e.g., category agreement) or send to a light-weight review queue.
* Keep a review queue for `0.60–0.80`.
* Track result distributions by source to calibrate thresholds.

<Note>
  Because responses only include matches, “no match” is represented as an empty `features` array.
</Note>