Location

A Location field collects the client’s geographic location: the latitude and longitude of a point, shown on a Google map.

The Location field is available in HTML templates only, when maps are included in your organization’s plan. A new location field can be filled in by the client only, and it isn’t required. For the settings that all fields share, such as the label, permissions, dependencies and style, see Field settings.

Before you start

To show a map, the template needs a Google Maps connector with a Google Maps API key. Without it, the field only captures the client’s position and shows the coordinates. To get an API key, see the Google Maps documentation.

1. Open the template and click the Integrations tab.
2. Click Add Live Connector and select the Maps source.
3. In API token, enter your Google Maps API key and click Verify. The key must be verified successfully.
4. To let the client search for an address or a place on the map, turn on Apply Geocoding.
5. Save the connector.

See Template integrations.

Settings

Drag Location from the palette. Give the field at least half the width of the row, so the map is large enough on a desktop screen.

On the Values & Display tab:

Setting	What it does
Display Map on final PDF result	Shows the map with the selected location in the result PDF.
Display Location coordinates [longitude/latitude] on final PDF result	Shows the coordinates in the result PDF.

What the client sees

1. When the form opens, the browser asks the client for permission to share their location. The permission is granted in the browser. Cellosign and Google can’t grant it.
2. If the client allows it, their current position is marked on the map.
3. The client can click the map to mark another point. If Apply Geocoding is on, they can also search for an address or a place.

If the client doesn’t allow the browser to share their location, they can still search or mark their location on the map.

Location data is sensitive. To ask for the client’s consent first, hide the location field by default and show it with a dependency on a consent checkbox, for example “I agree to share my location”.

The location in the results

The value of the field is the latitude and longitude, separated by a comma. When the map is available, the address of the point, as found by Google Maps, is also saved in the field’s meta.geocoder. For example, in a webhook:

{
  "id": "SOMEFIELD5",
  "type": "location",
  "value": "32.001186,34.9413393",
  "meta": {
    "geocoder": "Arlozorov St 160, Tel Aviv-Yafo, Israel"
  }
}

A Location field can’t be used in conditions.