Handling the onSelect Response

When a visitor chooses a point on the embedded map, UPCS calls your onSelect function with a JSON object. This page explains each field and how to use it safely.

The fields

• success: true when the location was resolved.
• upcs_code: the code, in the form CC-XXXX-XXXX, such as PK-1A2B-3C4D.
• latitude and longitude: the centre of the 3 m by 3 m cell that contains the selected point.
• address: a human-readable address string for the point.
• country_code: the two-letter country.
• cell: the 3 m by 3 m cell, with bounds (north, south, east, west) and center.
• saved: whether the location was saved.
• share_url: a link you can show or send.

A handler

function onSelect(result) {
  if (!result.success) return;

  document.querySelector('#upcs_code').value = result.upcs_code;
  document.querySelector('#lat').value = result.latitude;
  document.querySelector('#lng').value = result.longitude;
  document.querySelector('#upcs-summary').textContent =
    result.upcs_code + (result.address ? ' - ' + result.address : '');
}

Writing values into hidden form fields lets the normal form submission carry them to your server.

Validate on the server

Anything posted from a page can be edited by the user. Before you accept a code with an order, call the lookup endpoint from your server and confirm the code exists and matches the coordinates you expect. Do the same checks you would for any input, and see storing a UPCS code in your database.

What to store

At minimum keep upcs_code. Many shops also keep latitude and longitude so a courier can open the exact point, and the share_url; see showing the share_url. The cell.bounds can be drawn on your own map, as described in displaying cell bounds.

Keep the address field

The UPCS code complements the postal address; it does not replace it. Keep your normal address fields so carriers and invoices work as before.