Generate and Store a UPCS Code via the API

The generate endpoint creates a UPCS code for coordinates and lets you attach an address and a label to it. It is the right call when your system knows where something is and wants a code to keep.

The request

curl -X POST https://api.upcs.io/api/v1/upcs/generate \
  -H "x-api-key: upcs_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "latitude": 31.5204,
    "longitude": 74.3587,
    "address": "12 Example Street",
    "label": "Main entrance"
  }'

Field	Required	Notes
latitude	Yes	Latitude of the point.
longitude	Yes	Longitude of the point.
address	No	Address text to attach.
label	No	A short name for the place.

The response

• upcs_code: the code, CC-XXXX-XXXX.
• is_existing: true if a code already existed for that location.
• share_url: a link to share.

Steps

1. Validate that the point is a real latitude and longitude.
2. Call the endpoint from your server.
3. Save upcs_code with your customer or order record.
4. Share share_url if you want someone to open it.

Same place, same code

Each code corresponds to a 3 m x 3 m cell, and the same coordinates give the same code. A second call for a nearby point inside the same cell returns the same code, with is_existing set to true.

Errors

• 422 unsupported_location for points outside the supported countries.
• 422 for invalid coordinates.
• 401 or 403 for key problems; see error codes explained.

To read a code back, use look up a code.