Look Up a UPCS Code With the API

The lookup endpoint turns a stored UPCS code back into a location. Use it to confirm a code a customer gave you, or to get coordinates for routing.

The request

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

Replace the code at the end of the path with the one you want to look up. The key goes in the x-api-key header, as for every server-to-server call.

The response

The response includes:

• upcs_code: the code.
• location: an object with latitude, longitude, address, label, country_code and country_flag.
• Map links for opening the location.
• share_url: a link to share the code.

Steps

1. Normalise the code the user typed: trim spaces and use the CC-XXXX-XXXX pattern.
2. Call the endpoint from your server.
3. Read location.latitude and location.longitude to place the point on your map or in a routing request.
4. Show location.address or location.label if you need text.

Unknown codes

A code that is not found returns 404. Codes are found when they have been stored, for example through save: true on resolve or through the generate endpoint. Show the user a clear message and ask them to check the code. A well-formed but unknown code is different from a malformed one, so check the format before you call.

Related

• Create codes: generate and store a code or resolve coordinates.
• For people, not code: the help center shows how to find a location from a code on upcs.io.
• Authentication errors are explained in error codes.

Practical tip

Cache lookups for codes you use repeatedly, for example the delivery location of an open order, instead of calling the endpoint on every page view. This keeps your request count low and your pages fast, and it helps you stay within the hourly limit for the key.