POST /v1/validate
https://api.voygr.tech/v1/validate
Overview
Validate a place's existence and operating status using evidence about the place.
Authentication
- API key in header
X-API-Key: Your customer API key (pk_live_...), sent on every request. Self-serve at https://api.voygr.tech/checkout.
Request body
required
application/json
Schema: POIValidateRequest
Responses
200
Successful Response
application/json
Schema: POIValidateResponse
400
Invalid request. Correct the fields before retrying.
application/json
Schema: object | object
Option 1 fields
| Field | Type | Required | Description and constraints | ||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
success | boolean | required | constant False | ||||||||||||||||
error | string | required | |||||||||||||||||
error_code | string | required | constant VALIDATION_ERROR | ||||||||||||||||
request_id | string | null | required | |||||||||||||||||
validation_timestamp | string | required | |||||||||||||||||
detail | array of object | required | Item fields
|
Option 2 fields
| Field | Type | Required | Description and constraints | ||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
detail | object | required | Gateway rejection, for example an invalid Idempotency-Key header.Fields
|
One of
- Option 1: requires
success,error,error_code,request_id,validation_timestamp,detail - Option 2: requires
detail
invalidinput
{
"success": false,
"error": "Invalid input provided",
"error_code": "VALIDATION_ERROR",
"request_id": "example-request-id",
"validation_timestamp": "2026-09-16T12:00:00Z",
"detail": [
{
"field": "poi_name",
"message": "Field required",
"type": "missing"
}
]
}401
Missing or invalid X-API-Key.
application/json
X-API-Key header absent
{
"detail": {
"error": "API key required"
}
}X-API-Key doesn't resolve to an active key
{
"detail": {
"error": "invalid API key"
}
}402
The available balance cannot cover the request's credit hold. Nothing ran.
application/json
quotaexceeded
{
"detail": {
"error": "quota_exceeded",
"needed_credits": 10,
"checkout_url": "/checkout/buy"
}
}403
The key lacks the entitlement this operation requires.
application/json
notentitled
{
"error": "missing entitlement: validate_raw",
"error_code": "MISSING_ENTITLEMENT",
"entitlements": [
"validate_raw"
]
}429
Rate limit exceeded; wait and follow Retry-After when returned. Free keys are limited to 10 requests per second and 120 requests per minute, and can place 1 call at a time, up to 25 calls per day. Paid keys are limited to 10 requests per second and 120 requests per minute. A top-up raises a key's daily cap to 5,000 calls and its concurrent-call ceiling to 10. Enterprise limits are set per contract.
application/json
ratelimited
{
"detail": {
"error": "rate limit exceeded"
}
}502
The service behind the gateway failed. Nothing is charged; retry later.
application/json
backenderror
{
"error": "backend error",
"error_code": "BACKEND_ERROR"
}504
The service behind the gateway did not answer in time. Nothing is charged; retry later.
application/json
backendtimeout
{
"error": "backend timeout",
"error_code": "BACKEND_TIMEOUT"
}Schemas
POIValidateRequest
Type: object
Request model for single POI validation.
| Field | Type | Required | Description and constraints |
|---|---|---|---|
id | string (max length 100) | null | optional | Client-provided identifier |
poi_name | string | required | POI name length 1 to 200 |
street | string (max length 300) | null | optional | Street address |
city | string (max length 200) | null | optional | City |
region | string (max length 200) | null | optional | State/province |
postcode | string (max length 40) | null | optional | Postal/ZIP code |
country | string | null | optional | 2-letter ISO country code |
address | string (max length 500) | null | optional | Unstructured address string. May also be sent as freeform_address (input-only alias). |
latitude | number (-90.0 to 90.0) | null | optional | Latitude in decimal degrees (WGS84). Optional but recommended. |
longitude | number (-180.0 to 180.0) | null | optional | Longitude in decimal degrees (WGS84). Optional but recommended. |
Example
{
"id": "bakery-001",
"poi_name": "Example Bakery",
"address": "123 Example Street",
"country": "US",
"latitude": 37.7749,
"longitude": -122.4194
}POIValidateResponse
Type: object
Validation results describing existence and operating status separately.
| Field | Type | Required | Description and constraints |
|---|---|---|---|
success | boolean | required | Whether validation succeeded |
id | string | null | optional | Client-provided ID (pass-through) |
existence_confidence | number | null | optional | Confidence (0-1) that a matching place ever existed at this address. A score of 0.5 or more means we judge that the place exists. Below 0.5 we judge that it does not. A closed place can still have high existence confidence. This does not describe whether it is operating today. Interpret closure only when existence is established; use operational_status.status for the decision. |
operational_status | OperationalStatusBlock | null | optional | Operating-status result. Use operational_status.status for the decision. |
error | string | null | optional | Error message if success=false |
error_code | string | null | optional | Error category code (VALIDATION_ERROR, MODEL_ERROR, EXTERNAL_API_ERROR, etc.) |
request_id | string | null | optional | Request ID for tracing |
validation_timestamp | string | null | optional | UTC timestamp when validation was produced (ISO 8601). |
OperationalStatusBlock
Type: object
Operational status for a place. Use operational_status.status for the decision. A closed verdict is evidence-backed, not a decision based on score alone. closure_confidence sits above 0.5 for 'closed' and below 0.5 for 'open', and is not a probability. 'unknown' means the place exists but the evidence does not say whether it is open or closed; null means no closure assessment, not zero confidence.
| Field | Type | Required | Description and constraints |
|---|---|---|---|
status | string | required | Operational status. 'open' means assessed as operating. 'closed' means evidence supports closure. 'unknown' means the place exists but the evidence does not say whether it is open or closed, so re-check it later. 'not_exists' means the place was not judged to exist and no closure assessment was made. closure_confidence and closure_reason are null for 'unknown' and 'not_exists'. one of open, closed, unknown, not_exists |
closure_confidence | number | null | required | How strongly the closure model leans closed (0-1). Above 0.5 when operational_status.status is 'closed', below 0.5 when it is 'open'. On each side, a higher number means a stronger lean towards closed. Rank places with it within one status. The same number means a different chance of closure in different lists, so it is not a probability. It is null, not zero, when the status is 'unknown' or 'not_exists': we make no open or closed call. Use operational_status.status for the decision. |
closure_reason | string (one of permanent, temporary, relocated, replaced, dissolved, unspecified) | null | optional | What kind of evidence closed the place: permanent, temporary, relocated, replaced, dissolved, or unspecified. Null whenever status is not 'closed': an open or unknown verdict has no closure to attribute. |
On this page
