Authentication

All API endpoints require authentication via the X-API-Key header.

API Key Usage

Include your API key in every request:

curl -X POST https://geocoder.amigocloud.com/api/v1/{customer_uuid}/geocode/ \
  -H "X-API-Key: pk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"address": "Costanera Center, Santiago", "country": "CHL"}'

Key Properties

Each API key has:

Rate limits: Per-minute and per-day request caps
Domain restrictions: Optional whitelist of allowed origin domains (supports wildcards like *.example.com)
IP restrictions: Optional whitelist of allowed client IP addresses
Expiration: Optional expiration date

Security Restrictions

Domain Validation

If domain restrictions are configured, requests must include a matching Origin or Referer header:

Origin: https://app.example.com

IP Validation

If IP restrictions are configured, the client IP must be in the whitelist. The service checks these headers in order:

X-Forwarded-For (standard proxy header)
X-Real-IP
X-Client-IP
REMOTE_ADDR

Error Responses

Status	Meaning
`401`	Missing or invalid API key
`403`	Key expired, domain blocked, or IP blocked
`429`	Rate limit exceeded