Fieldmotion API Getting started

Work areas and stock categories

Query mapped work-area table rows

POST /a/Locations_getDataTable

Query the mapped work-area collection with DataTables counts or an unpaged data wrapper.

When to use this endpoint

Location_getRequestedDetails is simpler for an unpaged mapped detail lookup; use this endpoint when your table needs filtered counts, search and explicit page limits.

These records represent work areas and map locations, not live user GPS positions or geofence definitions. Read IDs before editing; the stored user column is distinct from user-to-area membership.

Authentication and permissions

Authenticate using signed API-key fields or a logged-in CRM session. All object queries use the authenticated tenant. The handler has no additional page, role or feature check unless stated below.

Sign numeric request values as strings, including nested native arrays; only JSON-encode parameters that explicitly accept JSON text. See Getting started.

Parameters

ParameterTypeRequiredDescription
fieldsNative arrayYesMapped names id, name, latitude, longitude, changes, lastEdited, address, user, customerType, customer; id always included. Native arrays only, not JSON text.
isTableInteger-compatibleNoDefault table mode; zero returns only {data:[...]}, without draw/counts or start/length paging.
start / length / drawInteger-compatibleNoTable defaults start=0, length=10, draw=0. length is used literally; -1 is not an all-rows token.
limitInteger-compatibleNoOnly in isTable=0 mode: positive limit caps returned rows; zero/omitted has no cap.
orderBy / orderDescStringNoBoth needed for named table ordering. Mapped name (case-insensitive fallback), direction asc/desc. Alternatively order[0]={column:1,dir:asc}; column subtracts one before selecting a non-id field.
searchValue / searchFieldString / name or native arrayNoTrimmed case-insensitive LIKE substring across selected mapped search fields, default All; SQL wildcard characters remain wildcards.
Mapped field filtersScalar or native arrayNoNames id, name, latitude, longitude, changes, lastEdited, address, user, customerType, customer. Text scalars use trimmed case-insensitive LIKE, text arrays use IN. Numeric filters coerce via the shared helper; not the equality semantics of the detail endpoint.
referenceDate / dateFrom / dateToMapped name / integer day offsetsNoRecognized referenceDate plus both offsets enables an inclusive range from local today+dateFrom 00:00:00 to today+dateTo 23:59:59; normally referenceDate=lastEdited. Tenant timezone determines today, blank falls back UTC.
offsetFrom / offsetToNative objectsNoOptional hour/minute offsets shift generated date bounds; hours negated, minutes added. Hour filtering uses offsetFrom.hour.
timeRangeFrom / timeRangeToInteger hoursNoWith a referenceDate, from triggers inclusive hour filtering; to alone does not. Defaults 0..23, inverted bounds swapped. Tenant timezone (blank Europe/London) is applied to stored GMT datetimes.
groupByNative mapped-name arrayNoAdds SQL grouping on recognized fields; counts are calculated without that grouping and are not group counts.
advanceSearchNative arrayNoLegacy advanced rules with column/id, condition and value; equal, notEqual, contains, greaterThan, greaterThanOrEqual, lesserThan, lesserThanOrEqual. andOr joins to the next rule (AND/OR/XOR), special adds parentheses. Raw where clauses are rejected. Use mapped-field rules only.

Example request

$result = FM_api('Locations_getDataTable', ['fields'=>['name','latitude'], 'start'=>'0', 'length'=>'10', 'draw'=>'1']);

Example response

{"data":[{"name":"Depot","latitude":"54.6","id":"1042"}],"draw":1,"recordsTotal":"1","recordsFiltered":"1"}

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: fields"}Fields omitted.
{"error":"error in database query"}Query failed, including invalid paging limits.
{"error":"unsupported raw advanced search"}An advanced rule includes raw where SQL.
{"error":"missing or invalid parameter: fields"}A supplied fields value is not a native string array.
{"error":"missing or invalid parameter: orderDesc"}Supplied named ordering direction is not asc or desc.

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

Behaviour and edge cases

  • Table mode sorts by the resolved first non-id requested field ascending unless ordering is supplied. Non-table mode lacks default sorting, except ascending reference-date ordering.
  • recordsTotal counts the non-deleted collection; recordsFiltered applies filters before paging. Counts are database scalars; data is an array, draw a JSON number.
  • A legacy helper detail: fractional coordinate scalar filters use integer conversion, so use validated advanced comparisons only when exact coordinate comparisons are needed.
  • Only non-deleted work areas are read or changed. No department or ownership restriction is applied. CRM1/CRM2 hide Area Settings with feature bit 524288, but these APIs do not enforce that UI restriction.
  • The source search found no direct caller in the mobile JavaScript app or its m/www intermediary for this endpoint.
  • Rejects raw advanced-search where clauses and non-native fields/advanced-rule arrays before invoking the mapped helper.

Side effects

  • Read-only; no object writes, audit entries or notifications are performed.

See it in Fieldmotion

CRM1

No direct CRM1 caller was found for this endpoint. The legacy Area Settings screen uses Locations_get and Location_get.

CRM2

No direct CRM2 caller was found for this endpoint. CRM2 Area Settings uses Locations_get and legacy Location_add/Location_edit writes.

Related endpoints