UPCS Logo
    My Account

    Developers — Guides

    Building location features: APIs, embeds, address data and integration practices.

    Developers

    Embed the UPCS Map on a WebsiteAdd the UPCS location picker to your own site in four steps: register an origin, create a session on your server, load the script and mount the map.Create a UPCS Embed Session with cURLCreate a UPCS embed session from the command line with cURL, read the session_token, and understand the common error responses.Create a UPCS Embed Session in Node.jsNode.js example for creating a UPCS embed session on your server with fetch, including error handling and what to return to the browser.Create a UPCS Embed Session in PHPPHP example using cURL to create a UPCS embed session on your server, parse the session_token and handle error responses safely.Create a UPCS Embed Session in PythonPython example using the requests library to create a UPCS embed session on your server and return only the session token to the browser.UPCS.mount Options ExplainedReference for every UPCS.mount option: sessionToken, height, center, zoom, style, onSelect, onError and onReady, plus the returned handle.Handling the onSelect ResponseWhat the UPCS embed onSelect callback returns, which fields to store, and a safe pattern for validating and saving the selected location.Handle onError and session_expiredHow to react to errors in the UPCS embed, especially session_expired: show a clear message, request a fresh session and remount the map.Allowed Origins ExplainedWhat an allowed origin is in UPCS, how to register one in the partner panel, the https rule, and how to fix origin_not_allowed errors.Local Development with localhostRun the UPCS embed on your own machine: register a localhost origin, create sessions from a local server and avoid common port mismatches.Server-to-Server Resolve EndpointUse POST /v1/embed/resolve to turn latitude and longitude into a UPCS code from your server, with optional saving and error handling.Look Up a UPCS Code with the APICall GET /v1/upcs/lookup/{code} to get coordinates, address, country and share link for a UPCS code, and handle the 404 for unknown codes.Generate and Save a UPCS Code via APIUse POST /v1/upcs/generate with latitude and longitude to create a UPCS code, optionally with an address and label, and read is_existing.Rate Limits and Backoff StrategyUPCS API keys have an hourly request limit. Learn how to recognise rate_limited responses and retry with exponential backoff and jitter.UPCS API Error Codes ReferenceReference for UPCS API errors: session_expired, key_inactive, partner_required, origin_not_allowed, unsupported_location, rate_limited and more.How to Secure Your UPCS API KeyKeep your UPCS API key safe: store it on the server, load it from environment variables, restrict origins and IPs, and respond if it leaks.Store a UPCS Code in Your DatabaseColumn type, length, indexing and loose format validation for storing UPCS codes in SQL, plus why a lookup beats relying on a regex alone.Showing the UPCS share_urlUse the share_url returned by UPCS in order pages, emails and driver apps so anyone can open the exact location from a single link.Display UPCS Cell Bounds on Your Own MapDraw the 3 m by 3 m UPCS cell on your own map using the north, south, east and west bounds returned by the API, with a Leaflet example.Use the UPCS Embed in ReactAn illustrative React pattern for the UPCS embeddable map: fetch a session token, mount in an effect, handle callbacks and destroy on unmount.Use the UPCS Embed in VueAn illustrative Vue 3 pattern for the UPCS embeddable map: load the script, mount on onMounted, emit the selection and destroy on unmount.Use the UPCS Embed in Plain HTMLAn illustrative plain HTML and JavaScript pattern for the UPCS map: a form with hidden fields, a session token fetch and onSelect handling.Add the UPCS Map to a Checkout PageDesign and build a UPCS location picker into a custom checkout: where to place it, optional behaviour, server checks and what to do on failure.Save the UPCS Code with an OrderPersist a customer's UPCS code, coordinates and share link with an order in your own database, with server-side verification and a schema example.Magento and UPCS: A Conceptual ApproachUPCS has no ready-made Magento extension. This conceptual guide outlines how a developer could combine the embeddable map and REST API in Magento.Laravel Example: Create a UPCS Embed SessionA Laravel controller and route that use the HTTP client to create a UPCS embed session with your API key and return the session token to the page.Django Example: Create a UPCS Embed SessionA Django view and URL route that call the UPCS embed session API with requests and return a session token as JSON for your page.Express Example: Create a UPCS Embed SessionAn Express.js route that creates a UPCS embed session with fetch, rate limits itself and returns only the session token to the browser.Storing Coordinates in a DatabaseHow to store latitude and longitude in a database: DECIMAL versus FLOAT, sensible precision, column order, ranges and when to use spatial types.PostGIS and Geospatial Basics for DevelopersA concept-level introduction to PostGIS and spatial databases: geometry versus geography, SRID 4326, spatial indexes and typical proximity queries.Reverse Geocoding Concepts for DevelopersWhat reverse geocoding is, how it differs from forward geocoding and location codes, and its limits for delivery and address data.Designing Address Forms with a Location FieldPractical address form design for international users, adding an optional map or UPCS code field without breaking existing address entry.Location Data and GDPR: Concepts for DevelopersA concept-level overview of privacy considerations for precise location data: minimisation, purpose, retention, security and user rights. Not legal advice.Caching Strategies for Location LookupsReduce API calls and stay inside your hourly limit by caching UPCS lookups and resolve results with sensible keys, TTLs and invalidation.Idempotency for Location API CallsMake retries safe: what idempotency means, why UPCS code generation is naturally repeatable, and how to avoid duplicate order locations.Testing a Location IntegrationHow to test a UPCS integration: mock the API in unit tests, cover error paths, run a small live smoke test and check the browser embed manually.API Key Rotation Best PracticesRotate your UPCS API key without downtime: create a replacement, deploy it, verify traffic, then disable the old key. Includes an emergency plan.Is There a UPCS SDK or Client Library?UPCS has no official SDKs or client libraries. Learn what you use instead: the embed script, plain HTTPS calls and the x-api-key header.Embed Lifecycle: Mount and DestroyManage the UPCS embed lifecycle in single-page apps: the handle returned by UPCS.mount, calling destroy, remounting and avoiding duplicate iframes.Embed Session TTL and RenewalChoose a ttl between 60 and 3600 seconds for UPCS embed sessions, read expires_at, and renew sessions before visitors see an expired map.Validate Coordinates Before API CallsCheck latitude and longitude ranges, types and placeholder values before calling UPCS, to avoid 422 errors and wasted hourly requests.Handling the unsupported_location ErrorWhat the UPCS unsupported_location (422) error means, which countries are supported, and how to fall back gracefully to a normal address.Grid Cell Codes vs Geohash: A Conceptual ComparisonHow grid-based location codes such as UPCS compare with geohash, plus codes and what3words-style systems in concept, and when each idea fits.Content Security Policy for the UPCS EmbedConfigure Content-Security-Policy so the UPCS embed script and map iframe can load: script-src, frame-src and connect-src, with a testing approach.Monitoring and Logging API UsageWhat to log and monitor for a UPCS integration: status codes, error codes, latency and hourly request volume, without leaking keys or locations.