Quick Start: Embed the UPCS Map on Your Site

Embedding the map takes four steps: get a key and origin, create a session on your server, load the script, and mount. Your API key stays on the server; the page only receives a short-lived session token.

1. Prepare access

1. Create a partner account.
2. Generate an API key.
3. Register your site as an allowed origin, for example https://shop.example.com.

2. Create a session on your server

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

The response contains session_token, expires_at and embed_url. Pass the session_token to your page. Details: create a map session.

3. Load the script and mount

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

See mount the map for every option.

4. Use the result

When a user picks a spot, onSelect receives the UPCS code, coordinates and more. Read the click response lists each field.

Checklist before going live

• The origin is https and registered.
• The key is not in the page source.
• You handle expired sessions; see session expiry.
• You have gone through the security checklist.

Where to go next

Once the basic flow works, add error handling in onError, decide how long sessions should live, and store the returned code with your order or record. The remaining pages in this section cover each endpoint and callback in detail, so you can add them one at a time.