Territory Lookup

The Territory Lookup REST API lets you query and inspect the territories defined in your EasyTerritory project, including their geometry, component geographies, and related metadata. All requests must be authenticated using an OI token, passed either as a cookie (oitoken) or as a request parameter.

Typical use cases include:

• Querying territories by ZIP/Postal Code.
• Looking up territories based on a latitude/longitude point.
• Retrieving full territory geometry and metadata for mapping and analytics.

Initial Setup

Before using the Territory Lookup API, complete these steps:

1. Build a Project
   • Create an EasyTerritory project containing territories using geographies (e.g., ZIP/Postal Codes, State boundaries).
   • Configure the ProjectMarkupPlugin.
2. Authenticate
   • Follow the Authentication Guide to retrieve an oitoken.
3. Call Territory Lookup API

REST API Endpoints

Get Project Markup (All Territories)

Retrieves the full geometry and parts (e.g., ZIP Codes) that make up each territory.

Endpoint:

GET https://apps.www.easyterritory.com/{YourEZTInstanceGuid}/{YourEZTInstanceType}/REST/ProjectMarkupPolygon/{projectId}

Get Territory by Geography

Retrieves territory details for a specific geography (e.g., ZIP code → mapped territory).

Endpoint:

GET https://apps.www.easyterritory.com/{YourEZTInstanceGuid}/{YourEZTInstanceType}/REST/ProjectMarkupPolygon/{projectId}/territory?territoryId={territoryId}

Get Territory by Latitude/Longitude

Returns all territories containing the supplied coordinates.

Endpoint:

GET https://apps.www.easyterritory.com/{YourEZTInstanceGuid}/{YourEZTInstanceType}/REST/ProjectMarkupPolygon/{projectId}/location?lat={latitude}&lon={longitude}

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
omitWkt	No	Boolean	When true, omits the Well-Known Text (WKT) representation from the response JSON.
omitWkt	No	Boolean	When true, omit metadata from response JSON.
maxVerticies	No	Integer	Specifies the maximum number of vertices to use when simplifying the Well-Known Text (WKT) geometry included in the response JSON. If parameter is not included the WKT is not simplified.
oiToken	No	String	Pass OI Token as parameter instead of a cookie.

Response JSON

{        
    primaryKey: number; // C# long
    wkt: string;
    projectId: string;
    markupId: string;
    tag: string;
    metadataJson: string;
    col1: string;
    col2: string;
    col3: string;
    col4: string;
    col5: string;
    col6: string;
    col7: string;
    col8: string;
}

Sample Request

(Get Territory by Latitude/Longitude)

cURL

curl -X GET \
  "https://apps.www.easyterritory.com/12345678-1234-1234-1234-123456789abc/APP/REST/ProjectMarkupPolygon/SalesTerritories/location?lat=30.4383&lon=-84.2807&omitWkt=false&maxVerticies=5000" \
  -H "Content-Type: application/json" \
  -H "Cookie: oitoken=abcdeabcdeabcde"

Sample Response

JSON

[
  {
    "primaryKey": 201001,
    "wkt": "POLYGON((-84.2900 30.4330, -84.2700 30.4330, -84.2700 30.4450, -84.2900 30.4450, -84.2900 30.4330))",
    "projectId": "SalesTerritories",
    "markupId": "TALLY-DOWNTOWN",
    "tag": "Tallahassee | Downtown Territory",
    "metadataJson": "32301,32304",
    "col1": "North Florida Region",
    "col2": "Downtown Tallahassee",
    "col3": "Manager: Jane Doe",
    "col4": "Channel: Direct",
    "col5": "Segment: SMB",
    "col6": "",
    "col7": "",
    "col8": ""
  }
]