Fieldmotion API Getting started

Customers

Geocode a customer address

POST /a/Customer_geocode

Resolve a customer’s stored address to coordinates without changing the customer record.

When to use this endpoint

Use Customer_geocode to offer a map position derived from the current customer address. Review the returned point, then save it separately if appropriate.

Do not assume that calling this endpoint updates latitude or longitude; it is a lookup only.

Authentication and permissions

The request must authenticate with signed API-key fields or a logged-in CRM session. The handler performs no additional page or role-permission check.

The lookup and any write use the authenticated tenant; an ID from another tenant cannot be addressed through this call.

Parameters

ParameterTypeRequiredDescription
idInteger stringYesCustomer whose name and address fields are sent to the shared geocoder.

Example request

$point = FM_api('Customer_geocode', [
	'id' => '1042',
]);

Example response

{
  "lat": "54.5973",
  "lon": "-5.9301"
}

Depending on the provider path, a successful result can be one point object or a one-element array containing it. Provider responses can contain additional display fields.

Errors and unusual responses

ResponseCondition
{"error":"not logged in"}No authenticated tenant context is available. Invalid signed credentials can be rejected by the dispatcher before the handler runs.
{"error":"missing or invalid parameter: id"}id is absent or not positive.
{"error":"missing customer: 1042"}No customer row has that ID.
{"error":"missing or invalid parameter: address"}All supported stored address components are blank.
{"error":"failed to geocode address"}No configured provider returns a usable result.

Legacy application errors may be returned with HTTP 200. Check the decoded response for error, not only the HTTP status.

Behaviour and edge cases

  • The customer lookup does not filter deleted=0, so a soft-deleted customer can be geocoded.
  • The query address joins nonblank address lines, town, city, county, postcode, state, and country. The customer name is fetched but is not included in the geocoding string.
  • The shared geocoder may infer country from an Irish postcode, use customer-default-country, or fall back to GBR.
  • It checks a file cache first, then may try an Irish/UK postcode service, OpenStreetMap Nominatim, and configured Google geocoding fallbacks.
  • There is no pagination.

Side effects

  • May make external geocoding requests and write the raw successful or failed lookup into the server’s /tmp/geolocate cache.
  • Does not update the customer, audit history, or activity logs.

See it in Fieldmotion

CRM1

On Customers, open the map action and choose Geolocate, or use the bulk geolocation action. Filter Network requests for Customer_geocode; CRM1 saves an accepted point with Customer_setLatLng.

CRM2

No direct production CRM2 caller was found. CRM2 address-edit saves can geocode indirectly through Customer_updateData.

Related endpoints