Enrich a place

POST /v1/enrich

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

Overview

Return requested place attributes: opening_hours, phone, website, facebook, instagram, tiktok, email. include_summary=true also returns a short factual place_summary. Requires a key permitted to use enrichment.

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: POIEnrichRequest

Responses

`200`

Successful Response

application/json

Schema: POIEnrichResponse

`422`

Coordinates could not be resolved to a location. Correct the coordinates or send an address.

application/json

Schema: object

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

unresolvedcoordinates

{
  "success": false,
  "error": "Could not resolve the given coordinates to a location.",
  "error_code": "VALIDATION_ERROR",
  "request_id": "example-request-id",
  "validation_timestamp": "2026-09-16T12:00:00Z"
}

`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

Field	Type	Required
`field`	`string`	required
`message`	`string`	required
`type`	`string`	required

Option 2 fields

Field Type Required Description and constraints

detail

object

required

Gateway rejection, for example an invalid Idempotency-Key header.

Fields

Field	Type	Required	Description and constraints
`error`	`string`	required
`error_code`	`string`	optional

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"
    }
  ]
}

Schemas

POIEnrichRequest

Type: object

Request model for place attribute enrichment.

Field	Type	Required	Description and constraints
`id`	`string (max length 100) \| null`	optional	Client-provided identifier
`poi_name`	`string`	required	Place name length 1 to 200
`street`	`string \| null`	optional	Street address
`city`	`string \| null`	optional	City
`region`	`string \| null`	optional	State/province
`postcode`	`string \| null`	optional	Postal/ZIP code
`country`	`string \| null`	optional	2-letter ISO country code (e.g. US) locating the place.
`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).
`longitude`	`number (-180.0 to 180.0) \| null`	optional	Longitude in decimal degrees (WGS84). Provide with latitude.
`attributes`	`array of string`	optional	Attributes to return: opening_hours, phone, website, facebook, instagram, tiktok, email. Existence and open_closed are returned under status. Defaults to opening_hours, phone, website, existence, open_closed. 1 to 9 items; default ['opening_hours', 'phone', 'website', 'existence', 'open_closed']
`include_summary`	`boolean`	optional	Also return a short factual place_summary. Default false. Does not change billing: still 1 credit. default False
`response_format`	`string`	optional	Response shape: 'attributes' (default, EnrichedAttribute) or 'cell' (the unified ResultCell shape). one of attributes, cell; default attributes

Example

{
  "id": "bakery-001",
  "poi_name": "Example Bakery",
  "address": "123 Example Street",
  "country": "US",
  "latitude": 37.7749,
  "longitude": -122.4194,
  "attributes": [
    "opening_hours",
    "phone",
    "website"
  ]
}

POIEnrichResponse

Type: object

Response model for place attribute enrichment.

Field	Type	Required	Description and constraints
`success`	`boolean`	required	Whether enrichment ran (individual attributes may still be null)
`id`	`string \| null`	optional	Client-provided ID (pass-through)
`attributes`	`object mapping names to EnrichedAttribute \| ResultCell \| null`	optional	Requested web-extracted attribute -> result (opening_hours, phone, website, facebook, instagram, tiktok, email). EnrichedAttribute by default; the unified ResultCell when the request sets response_format='cell'.
`status`	`EnrichStatus \| null`	optional	Existence and closure information; see EnrichStatus. Present when requested; null if validation is unavailable.
`operational_status`	`OperationalStatusBlock \| null`	optional	Operating-status result. Use operational_status.status for the decision.
`place_summary`	`string \| null`	optional	Short factual description of the place. Present only with include_summary=true; null when unavailable.
`enrichment_timestamp`	`string \| null`	optional	UTC timestamp (ISO 8601)
`error`	`string \| null`	optional	Error message if success=false
`error_code`	`string \| null`	optional	Error category code
`request_id`	`string \| null`	optional	Request ID for tracing

Example 1

{
  "success": true,
  "id": "poi-12345",
  "attributes": {
    "opening_hours": {
      "value": {
        "days": {
          "monday": "closed",
          "tuesday": [
            {
              "open": "11:30",
              "close": "22:00"
            }
          ],
          "wednesday": [
            {
              "open": "11:30",
              "close": "22:00"
            }
          ],
          "thursday": [
            {
              "open": "11:30",
              "close": "22:00"
            }
          ],
          "friday": [
            {
              "open": "11:30",
              "close": "23:00"
            }
          ],
          "saturday": [
            {
              "open": "11:30",
              "close": "23:00"
            }
          ],
          "sunday": [
            {
              "open": "11:00",
              "close": "22:00"
            }
          ]
        }
      },
      "confidence": "high"
    },
    "phone": {
      "value": {
        "number": "+14155551234"
      },
      "confidence": "medium"
    },
    "website": {
      "value": {
        "url": "https://www.zunicafe.com"
      },
      "confidence": "high"
    },
    "facebook": {
      "value": {
        "url": "https://www.facebook.com/zunicafe",
        "handle": "zunicafe"
      },
      "confidence": "high"
    },
    "email": {
      "value": {
        "email": "info@zunicafe.com"
      },
      "confidence": "medium"
    }
  },
  "status": {
    "existence_confidence": 0.98
  },
  "place_summary": "A Californian restaurant on Market Street serving a seasonal menu, open since 1979.",
  "enrichment_timestamp": "2026-06-29T12:34:56Z",
  "request_id": "ad33009a-fdfe-4e25-9650-4a49099c3d4a",
  "operational_status": {
    "status": "open",
    "closure_confidence": 0.02,
    "closure_reason": null
  }
}

EnrichedAttribute

Type: object

One attribute's value, confidence, and as_of date. Unavailable values are null.

Field	Type	Required	Description and constraints
`value`	`object \| null`	optional	Attribute payload (shape depends on the attribute); null if not found
`as_of`	`string \| null`	optional	Most recent date carried by the cited evidence (ISO); null when sources are undated (most are)
`confidence`	`string \| null`	optional	Confidence tier: high \| medium \| low. Null when the value is null.

Example 1

{
  "value": {
    "days": {
      "monday": "closed",
      "tuesday": [
        {
          "open": "11:30",
          "close": "22:00"
        }
      ],
      "wednesday": [
        {
          "open": "11:30",
          "close": "22:00"
        }
      ],
      "thursday": [
        {
          "open": "11:30",
          "close": "22:00"
        }
      ],
      "friday": [
        {
          "open": "11:30",
          "close": "23:00"
        }
      ],
      "saturday": [
        {
          "open": "11:30",
          "close": "23:00"
        }
      ],
      "sunday": [
        {
          "open": "11:00",
          "close": "22:00"
        }
      ]
    }
  },
  "confidence": "high"
}

ResultCell

Type: object

One returned value, confidence tier, and status, returned by enrichment in cell format. Unavailable values are null.

Field	Type	Required	Description and constraints
`value`	`any \| null`	optional	The field value; null when unconfirmed
`confidence`	`string \| null`	optional	Trust tier: high \| medium \| low; null when value is null
`status`	`string`	required	confirmed \| estimated \| unconfirmed \| cost_capped \| rejected. Estimated values have low confidence; filter by status if you need confirmed values only.

EnrichStatus

Type: object

Existence results returned alongside enriched attributes. Interpret closure only when existence is established; read operational_status.status for the decision. Unavailable validation can return null fields. An operational-status failure can return HTTP 503 with operational_status_unavailable; retry the request.

Field	Type	Required	Description and constraints
`existence_confidence`	`number \| null`	optional	Confidence (0-1) that a matching place ever existed at this address. 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. Example: `0.94`

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. Confidence is not a cross-status decision threshold. 'unknown' means undetermined; 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 undetermined and worth re-checking; 'not_exists' means the place was not judged to exist and no closure assessment was made. closure_confidence and closure_reason are null for 'not_exists'. one of open, closed, unknown, not_exists
`closure_confidence`	`number \| null`	required	Confidence in a closed verdict (0-1). Use operational_status.status for the decision; do not use confidence as a cross-status threshold or rank non-closed places by it. Null for 'not_exists' means no closure assessment, not zero confidence.
`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.