FAQ
Developer FAQ: UPCS API and Embed Map
Answers for developers about UPCS embed sessions, tokens, allowed origins, the onSelect response, resolve, lookup and generate endpoints, error codes and limits.
Updated 14 October 2026 · 4 min read
UPCS exposes a REST API and an embeddable map script for developers. These answers cover how sessions, tokens and origins work, what each endpoint returns and what the documented error codes mean. The full reference is in the API documentation.
Frequently asked questions
What does the UPCS API let a developer do?
It lets your server create embed sessions for the interactive map, resolve coordinates to a UPCS code, look up a code and generate a code for a latitude and longitude. The documentation describes the REST API and embed script.
Does UPCS provide official SDKs?
The documentation describes HTTP endpoints and an embed script, and no SDK is documented. You call the endpoints directly and load the embed script in the page.
How do I authenticate requests to the UPCS API?
Send your API key in the x-api-key header. The base URL for server requests is https://api.upcs.io/api, and keys start with upcs_.
How do I create an embed session?
From your server, send POST https://api.upcs.io/api/v1/embed/sessions with the x-api-key header and a JSON body such as {"origin":"https://shop.example.com"}. The response contains session_token, expires_at and embed_url.
How long does an embed session token last?
By default a session lasts 15 minutes. You can set the optional ttl field to a value between 60 and 3600 seconds.
Why must the session be created on the server?
The session request uses your secret API key, which must never be exposed in browser code. Your server creates the short-lived session and passes only the session token to the page.
How do I show the map on my page?
Load https://api.upcs.io/api/embed/upcs-embed.js and call UPCS.mount with a selector and an options object that includes your sessionToken. The call returns an object with the iframe and a destroy method.
Which options does UPCS.mount accept?
The options are sessionToken, height, center, zoom, style, onSelect, onError and onReady. The style can be streets (the default), satellite, traffic or biking.
At what zoom level does the grid appear?
The 3 m by 3 m grid appears from zoom level 18. Users need to zoom in to that level to pick a precise grid cell.
What does the onSelect callback return?
It receives JSON with success, upcs_code, latitude, longitude, address, country_code, cell, saved and share_url. The latitude and longitude are the centre of the selected 3 m by 3 m cell. The cell object contains bounds for north, south, east and west, and a center.
What does the saved field in the onSelect response mean?
It indicates whether the selected location was stored. With the resolve endpoint, sending save as true stores the result.
How do I convert coordinates to a UPCS code from my server?
Send POST https://api.upcs.io/api/v1/embed/resolve with the x-api-key header and a body containing lat, lng and save. The response has the same shape as the map click response.
How do I look up a UPCS code through the API?
Send GET https://api.upcs.io/api/v1/upcs/lookup/{code} with your x-api-key header. The response includes the upcs_code, a location object, map links and a share_url. A malformed code returns 400 and an unknown code returns 404, and those two error bodies use error and message fields.
What does the lookup response contain for the location?
The location object contains latitude, longitude, address, label, country_code and country_flag. The response also includes map links and the share_url.
How do I generate a UPCS code for a latitude and longitude?
Send POST https://api.upcs.io/api/v1/upcs/generate with latitude and longitude, plus optional address and label. The response gives the upcs_code, is_existing and share_url.
How do allowed origins work for the embed map?
The origin you send when creating a session must be registered under Allowed origins in the partner panel of the account that owns the key. Only https origins are accepted, and http://localhost:5173 works for development. Removing an origin immediately stops sessions that depend on it.
What do the 403 partner_required and origin_not_allowed errors mean?
Both come from the embed session request. partner_required means the API key is not linked to a partner account, so you need a key from a partner panel. origin_not_allowed means the origin you sent is not registered under Allowed origins in the partner account that owns the key.
Which errors return 422 and what do they mean?
A 422 response with the code unsupported_location means the point is outside the supported countries. A 422 validation error means a field such as the origin, lat or lng was invalid.
What is the rate limit and what happens when I exceed it?
Each key has an hourly limit, 1,000 requests per hour by default. Exceeding it returns 429 with the code rate_limited. Retry only after backing off, and do not retry 401, 403 or 422 errors, which need a fix instead.
What does an error response look like?
Errors are returned as JSON with success set to false, a message and, for many failures, a code. Check the HTTP status and the code field to decide how to respond. The lookup endpoint is the exception: its 400 and 404 bodies use error and message fields.
Do the same coordinates always return the same UPCS code?
Yes. A point is snapped to its 3 m by 3 m cell and the code is derived from that cell, so the same place always gives the same code and the code resolves back to that square.