Read the UPCS Map Click Response

When a user selects a spot on the embedded map, the onSelect callback you passed to UPCS.mount receives a JSON object describing that location.

Example

{
  "success": true,
  "upcs_code": "PK-1A2B-3C4D",
  "latitude": 31.5204,
  "longitude": 74.3587,
  "address": "Example address text",
  "country_code": "PK",
  "cell": {
    "bounds": {
      "north": 31.52042,
      "south": 31.52039,
      "east": 74.35872,
      "west": 74.35868
    },
    "center": { "lat": 31.52041, "lng": 74.3587 }
  },
  "saved": false,
  "share_url": "https://upcs.io/PK-1A2B-3C4D"
}

The numbers and address are illustrative.

Fields

Field	Meaning
success	Whether the selection worked.
upcs_code	The code for the selected cell, CC-XXXX-XXXX.
latitude, longitude	The centre of the selected cell.
address	Reverse-geocoded address; falls back to the coordinates if none is found.
country_code	Two-letter country code.
cell	The 3 m x 3 m cell: bounds (north, south, east, west) and center.
saved	true if the code was stored, which happens with server-to-server calls that set save to true.
share_url	A link to share the code.

Use it

onSelect: function (result) {
  if (!result.success) return;
  document.getElementById('upcs_code').value = result.upcs_code;
  document.getElementById('lat').value = result.latitude;
  document.getElementById('lng').value = result.longitude;
}

Remember that data from the browser can be changed by the user. If a code matters for a delivery or payment decision, confirm it on your server by resolving the coordinates again with server-to-server resolve.

If the selection fails

A point outside the supported countries returns unsupported_location; see supported countries. Other errors are in error codes explained.

Tip for forms

Disable your submit button until onSelect has returned a successful result, and show the selected code to the customer so they can confirm it. This avoids orders being placed with an empty location field and gives people a chance to correct a mis-click.