Skip to content

Validate a place

POST /v1/validate

https://api.voygr.tech/v1/validate

Open in playground

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

FieldTypeRequiredDescription and constraints
successbooleanrequiredconstant False
errorstringrequired
error_codestringrequiredconstant VALIDATION_ERROR
request_idstring | nullrequired
validation_timestampstringrequired
detailarray of objectrequired

Item fields

FieldTypeRequiredDescription and constraints
fieldstringrequired
messagestringrequired
typestringrequired

Option 2 fields

FieldTypeRequiredDescription and constraints
detailobjectrequiredGateway rejection, for example an invalid Idempotency-Key header.

Fields

FieldTypeRequiredDescription and constraints
errorstringrequired
error_codestringoptional

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.

FieldTypeRequiredDescription and constraints
idstring (max length 100) | nulloptionalClient-provided identifier
poi_namestringrequiredPOI name
length 1 to 200
streetstring (max length 300) | nulloptionalStreet address
citystring (max length 200) | nulloptionalCity
regionstring (max length 200) | nulloptionalState/province
postcodestring (max length 40) | nulloptionalPostal/ZIP code
countrystring | nulloptional2-letter ISO country code
addressstring (max length 500) | nulloptionalUnstructured address string. May also be sent as freeform_address (input-only alias).
latitudenumber (-90.0 to 90.0) | nulloptionalLatitude in decimal degrees (WGS84). Optional but recommended.
longitudenumber (-180.0 to 180.0) | nulloptionalLongitude 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.

FieldTypeRequiredDescription and constraints
successbooleanrequiredWhether validation succeeded
idstring | nulloptionalClient-provided ID (pass-through)
existence_confidencenumber | nulloptionalConfidence (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_statusOperationalStatusBlock | nulloptionalOperating-status result. Use operational_status.status for the decision.
errorstring | nulloptionalError message if success=false
error_codestring | nulloptionalError category code (VALIDATION_ERROR, MODEL_ERROR, EXTERNAL_API_ERROR, etc.)
request_idstring | nulloptionalRequest ID for tracing
validation_timestampstring | nulloptionalUTC 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.

FieldTypeRequiredDescription and constraints
statusstringrequiredOperational 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_confidencenumber | nullrequiredHow 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_reasonstring (one of permanent, temporary, relocated, replaced, dissolved, unspecified) | nulloptionalWhat 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.