Resolve Coordinates to a Code Server-to-Server

If you already have coordinates, for example from a form or a device, you can get the UPCS code for them straight from your server. No map and no session are involved. The request is authenticated with your API key.

The request

curl -X POST https://api.upcs.io/api/v1/embed/resolve \
  -H "x-api-key: upcs_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"lat": 31.5204, "lng": 74.3587, "save": false}'

Field	Notes
lat	Latitude.
lng	Longitude.
save	When true, the result is stored.

The response

The response has the same shape as the map click response: success, upcs_code, latitude, longitude, address, country_code, cell, saved and share_url.

Steps

1. Validate the coordinates on your side first.
2. Send the request from server code with the key in x-api-key.
3. Check success, then read upcs_code.
4. Store the code with your record if you need it later.

Errors to expect

• 422 unsupported_location: the point is outside the supported countries.
• 422 validation error: lat or lng is invalid.
• 401: the key is missing ("Missing API key") or wrong, disabled or expired ("Invalid or inactive API key"). There is no code field.
• 429 rate_limited: slow down; see handle the rate limit.

Resolve or generate?

Both turn coordinates into a code. Use resolve when you want the same response as the map gives. Use generate and store a code when you also want to attach an address or label.

Tip for batches of records

If you have many records to process, spread requests over time and store each result as you go. This keeps you within the hourly limit for the key and means a failure part-way through does not force you to start again from the beginning.