Embed the UPCS Map on a Website

The UPCS embeddable map lets visitors pick an exact location on your own page and get back a UPCS code. Embedding takes four steps: register your site's origin, create a short-lived session on your server, load the embed script, and mount the map into an element.

Step 1: Get a key and register your origin

Create a partner account at /partner, then create an API key in the partner panel. Keys start with upcs_. Add your site's origin (for example https://shop.example.com) under Allowed origins. Origins must be https; for local work see local development with localhost. More detail is in allowed origins explained.

Step 2: Create a session on your server

Your server calls POST https://api.upcs.io/api/v1/embed/sessions with the x-api-key header and a JSON body containing the page's origin. The response contains session_token, expires_at and embed_url.

curl -X POST https://api.upcs.io/api/v1/embed/sessions \
  -H "x-api-key: $UPCS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"origin":"https://shop.example.com"}'

Expose a small endpoint of your own (for example /upcs-session) that returns only the session_token to the page. Language-specific versions: cURL, Node.js, PHP and Python.

Step 3: Load the script and mount

<div id="upcs-map"></div>
<script src="https://api.upcs.io/api/embed/upcs-embed.js"></script>
<script>
  fetch('/upcs-session')
    .then(function (r) { return r.json(); })
    .then(function (data) {
      UPCS.mount('#upcs-map', {
        sessionToken: data.session_token,
        height: '500px',
        onSelect: function (result) {
          console.log(result.upcs_code, result.latitude, result.longitude);
        },
        onError: function (err) { console.error(err); }
      });
    });
</script>

The available options are covered in UPCS.mount options explained.

Step 4: Use the result

When the visitor chooses a point, onSelect receives the code, coordinates, address and cell bounds. Store at least the upcs_code with your record; see handling the onSelect response.

Checklist

• The origin sent when creating the session matches the page's origin exactly.
• The API key never appears in browser code.
• You handle onError, including session_expired: see handling onError and session_expired.

A UPCS code complements a normal address; it does not replace official postcodes, so keep your usual address fields.