Server-to-Server Resolve Endpoint

If you already have coordinates, for example from a mobile checkout or a courier scan, you do not need the embedded map. The resolve endpoint converts a latitude and longitude into a UPCS code from your server.

Request

POST https://api.upcs.io/api/v1/embed/resolve with the x-api-key header and a JSON body of lat, lng and save:

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

Note that this endpoint uses lat and lng, whereas the generate endpoint uses latitude and longitude.

Response

The response has the same shape as the embed click response described in handling the onSelect response. The returned coordinates are the centre of the 3 m by 3 m cell containing your point: success, upcs_code, latitude, longitude, address, country_code, cell, saved and share_url.

const res = await fetch('https://api.upcs.io/api/v1/embed/resolve', {
  method: 'POST',
  headers: { 'x-api-key': process.env.UPCS_API_KEY, 'Content-Type': 'application/json' },
  body: JSON.stringify({ lat, lng, save: true })
});
const data = await res.json();
if (!res.ok) throw new Error(data.code || data.message);

Errors

• 422 validation error: latitude or longitude is missing or out of range. Validate coordinates first.
• 422 unsupported_location: see handling unsupported_location.
• 401 and 403: key or IP problems.
• 429 rate_limited: slow down; see rate limits and backoff.

When to use it

Use resolve for batch-free, one-at-a-time conversions triggered by your own events. UPCS does not offer bulk upload, so loop politely with backoff if you must process several points. Because the same coordinates always produce the same code, you can cache results.