Look Up a UPCS Code with the API

A lookup turns a code such as PK-1A2B-3C4D back into a location. Use it to verify codes entered by customers and to fetch coordinates for routing or display.

Request

curl https://api.upcs.io/api/v1/upcs/lookup/PK-1A2B-3C4D \
  -H "x-api-key: $UPCS_API_KEY"

Response

The JSON contains upcs_code, a location object, a maps object with map links, and share_url. Inside location you will find latitude, longitude, address, label, country_code and country_flag.

async function lookup(code) {
  const res = await fetch(
    'https://api.upcs.io/api/v1/upcs/lookup/' + encodeURIComponent(code),
    { headers: { 'x-api-key': process.env.UPCS_API_KEY } }
  );
  if (res.status === 404 || res.status === 400) return null; // unknown or malformed code
  const data = await res.json();
  if (!res.ok) throw new Error(data.code || data.message || data.error);
  return data;
}

Using it for validation

A regular expression can reject obviously malformed input, but only a lookup confirms the code is real. The pattern below is a loose check for the CC-XXXX-XXXX format and is no substitute for the API call; see storing a UPCS code in your database.

const looksLikeUpcs = /^[A-Za-z]{2}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}$/;

Normalise case before comparing or storing, for example uppercasing, and trim whitespace.

Common patterns

• On order submission, look up the entered code, store the returned coordinates, and show the address back to the customer for confirmation.
• Cache successful lookups, because a code always refers to the same cell; see caching strategies.
• If you receive 429, use backoff.

Keep your key on the server and expose a small endpoint of your own to the browser. See securing your UPCS API key.