The Nearest Neighbor Lookup REST API returns the closest point features from an EasyTerritory project by supplying a latitude, longitude, and an authenticated request using an oitoken, making it easy to locate the nearest store, customer, asset, or other mapped entity. It supports optional filtering (layer, result count, attribute match) and responds with detailed information about each nearby feature, including distance, address data, and custom project fields.
Initial Setup
- Build Project
- Create an EasyTerritory project in the Territory Designer containing point location data.
- Configure the Project Points Plugin.
- Authenticate
- Retrieve an
oitokenby following the Authentication Guide.
- Retrieve an
Nearest Neighbor Endpoint
GET https://apps.easyterritory.com/{InstanceGuid}/{InstanceType}/REST/ProjectPointLayer/{projectId}/nearest
Notes:
- {YourGuid} → Your EasyTerritory GUID.
- {YourEZTInstanceType} → One of [DEV], [TEST], or [APP] (APP = Production).
- {ProjectId} → The target EasyTerritory project.
Request Headers
- Media Types: “application/json”
- Cookie: “oitoken={oiToken}”
URI Parameters
| Name | Required | Type | Description |
|---|---|---|---|
| lat | Yes | Number | Latitude of the location to search from. |
| lon | Yes | Number | Longitude of the location to search from. |
| layerId | No | String | Specific layer ID to query. Defaults to all custom point layers. |
| top | No | Number | Number of nearest features to return. Defaults to 1. |
| whereCol | No | String | Column name to filter results by. |
| whereVal | No | String | Value to match in the whereCol column. Uses equivalence test. |
| oiToken | No | String | Authentication token. Can also be passed as a cookie. |
Response Body
[
{
distance: number;
primaryKey: number;
wkt: string;
projectId: string;
layerId: string;
itemId: string;
name: string;
fullAddress: string;
markupTag: string;
geoStreet: string;
geoCity: string;
geoState: string;
geoPostal: string;
geoCountry: string;
geoQuality: string;
geoLatitude: number;
geoLongitude: number;
stat1: number;
stat2: number;
stat3: number;
stat4: number;
stat5: number;
stat6: number;
stat7: number;
stat8: number;
}
]
| Field | Description |
|---|---|
| distance | Distance to the queried point (in meters). |
| primaryKey | Primary key from the SQL table. |
| wkt | Well-Known Text representation of the geometry. |
| projectId | ID of the EasyTerritory project. |
| layerId | ID of the layer where the point is located. |
| itemId | Unique identifier of the item. |
| name | Name of the point record. |
| fullAddress | Full address string. |
| markupTag | Concatenated label: Group | Name. |
| geoStreet | Street portion of the address. |
| geoCity | City. |
| geoState | State. |
| geoPostal | Postal/ZIP code. |
| geoCountry | Country. |
| geoQuality | Quality of geocode. |
| geoLatitude | Latitude of the point. |
| geoLongitude | Longitude of the point. |
| stat1–stat8 | Numeric statistic fields defined in your project. |
Sample Request
cURL
curl -X GET \
"https://apps.easyterritory.com/12345678-1234-1234-1234-123456789abc/APP/REST/ProjectPointLayer/RetailStores/nearest?lat=29.9511&lon=-90.0715&top=3&layerId=Stores" \
-H "Content-Type: application/json" \
-H "Cookie: oitoken=abcdeabcdeabcdeabcde"
Sample Response
JSON
[
{
"distance": 185.42,
"primaryKey": 100245,
"wkt": "POINT(-84.2798 30.4388)",
"projectId": "RetailStores",
"layerId": "Stores",
"itemId": "STORE-00427",
"name": "Downtown Tallahassee Store",
"fullAddress": "200 S Adams St, Tallahassee, FL 32301, USA",
"markupTag": "Tallahassee District | Downtown Tallahassee Store",
"geoStreet": "200 S Adams St",
"geoCity": "Tallahassee",
"geoState": "FL",
"geoPostal": "32301",
"geoCountry": "USA",
"geoQuality": "Optimal",
"geoLatitude": 30.4388,
"geoLongitude": -84.2798,
"stat1": 1250000,
"stat2": 2800,
"stat3": 4.5,
"stat4": 10,
"stat5": 0,
"stat6": 0,
"stat7": 0,
"stat8": 0
}
]
