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;
}
]
Sample Request
GET /12345678-1234-1234-1234-123456789abc/APP/REST/ProjectPointLayer/RetailStores/nearest?lat=29.9511&lon=-90.0715&top=3&layerId=Stores HTTP/1.1
Host: apps.easyterritory.com
Content-Type: application/json
Cookie: oitoken=abcdeabcdeabcdeabcdecURL
Sample Response
[
{
"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
}
]
