Generate and Save a UPCS Code via API

The generate endpoint creates a code for a pair of coordinates and lets you attach an address and a label to it. It is the right call when your system already knows where something is and you want a code to print, send or store.

Request

POST https://api.upcs.io/api/v1/upcs/generate with x-api-key and a JSON body:

curl -X POST https://api.upcs.io/api/v1/upcs/generate \
  -H "x-api-key: $UPCS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"latitude":31.5204,"longitude":74.3587,"address":"Shop 4, Main Boulevard","label":"Warehouse gate"}'

Fields:

• latitude and longitude: required.
• address: optional text.
• label: optional short name.

Response

You receive upcs_code, is_existing and share_url, together with the latitude, longitude, address, label and country_code of the code.

{
  "success": true,
  "upcs_code": "PK-1A2B-3C4D",
  "is_existing": false,
  "share_url": "..."
}

is_existing: true means a code for that 3 m by 3 m cell was already present, so you did not create a duplicate. Because coordinates map deterministically to a cell, calling generate twice for the same point returns the same code; see idempotency for location API calls.

Generate versus resolve

Resolve uses lat, lng and save, and returns the richer map-click shaped response. Generate uses latitude and longitude and lets you add your own address and label. Pick the one that matches the data you have.

Errors to handle

• 422 validation error for invalid coordinates; check them first with validate coordinates before API calls.
• Points outside the supported countries are reported as unsupported_location; see handling unsupported_location.
• 401 or 403 for key or IP problems, and 429 rate_limited if the hourly limit is reached; see rate limits and backoff.

Store the returned code with your record using the advice in storing a UPCS code in your database.