Places API

Places API provides validation and enrichment for business records.

Check business details, enrich records with additional information, and process larger datasets with batch requests.

Quickstart

Set VOYGR_API_KEY in your server environment as described in Authentication. Start with one business record. Replace the example values with your own business details.

Validate a business

Use this quickstart when you have one business record and need confidence that the place exists, plus its current operating status.

Send a validation request

Send poi_name and a full address. Replace the sample business and location with the place you want to validate. Coordinates are optional but recommended for a more precise location match. When you provide coordinates, send both latitude and longitude in decimal degrees (WGS84). Keep the API key on your server.

curl https://api.voygr.tech/v1/validate \
  --request POST \
  --header "X-API-Key: $VOYGR_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "poi_name": "Example Bakery",
    "address": "123 Example Street, San Francisco, CA 94103, US",
    "latitude": 37.7749,
    "longitude": -122.4194
  }'

Interpret the validation response

success tells you whether validation completed. existence_confidence is a score from 0.0 to 1.0 that a matching place has existed at the supplied location. It does not say whether the business is open today; a permanently closed business can still have high existence confidence.

Use operational_status.status for the operating-status decision: open, closed, unknown, or not_exists. unknown is unresolved and worth re-checking. not_exists means the place itself was not judged to exist, so no closure assessment was made.

For a closed result, operational_status.closure_confidence indicates how strongly the closed verdict is held, and operational_status.closure_reason describes the kind of closure evidence. On any result other than closed, do not rank or compare closure_confidence; it is null for not_exists.

The response can also include your optional id, a request_id, and validation_timestamp. Retain request_id when contacting support.

Handle validation errors

400 means the request body is invalid; check poi_name, the location fields, and that coordinates are supplied as a pair.
401 means the API key is missing or invalid.
402 means the key has no validation credits remaining.
403 means the key cannot use this operation.
429 means the request exceeded a rate limit; wait before retrying.
500 or 503 means validation is temporarily unavailable; retry later.

Read error and error_code when present, and retain request_id when contacting support.

Enrich a business

Use this quickstart when you have one business record and want current contact details or opening hours.

Send an enrichment request

Send the business name, a location, and the attributes you want. Replace the sample name, address, and coordinates with the business you want to enrich, and keep the API key on your server.

When providing coordinates, send both latitude and longitude in decimal degrees (WGS84).

curl https://api.voygr.tech/v1/enrich \
  --request POST \
  --header "X-API-Key: $VOYGR_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "id": "bakery-001",
    "poi_name": "Example Bakery",
    "address": "123 Example Street",
    "latitude": 37.7749,
    "longitude": -122.4194,
    "country": "US",
    "attributes": ["opening_hours", "phone", "website"]
  }'

Interpret the enrichment response

success tells you whether enrichment ran. id repeats your identifier. The attributes object has one entry for each requested enrichment field; each entry contains value, confidence, and as_of. A null value means that attribute was unavailable.

If you request existence or open_closed, read the returned status and operational_status objects. If you set include_summary to true, the response can also contain place_summary.

Handle enrichment errors

401 means the API key is missing or invalid.
403 means the key cannot use this operation.
400 means the request is invalid; check poi_name, the location fields, and attributes. For VALIDATION_ERROR, read the detail entries (field, message, and type).
402 means the available balance cannot cover the request; add credits before retrying.
422 with error_code: VALIDATION_ERROR means a coordinates-only request could not be resolved to a location. Correct the coordinates or send an address. This response has error and request_id, without the detail list used by 400 request-validation errors.
429 means a rate or concurrency limit was reached; wait and follow Retry-After when returned.

When success is false, read error and error_code and retain request_id for troubleshooting.

API reference

Open the API reference →

Need help with access or an integration? Email support@voygr.tech.

Batch guides

Research guide

Research custom attributes