The Geocoding Service converts street addresses into their latitude/longitude equivalents. This enables you to plot records on a map or use them in spatial queries.
Note: To use this service, you’ll need to get your Azure Maps key from the Territory Designer administration panel.
Initial Setup
No authentication/ OI token needed. Access to the service is authorized using the Azure Maps key.
Geocode Service Endpoint
POST https://apps.easyterritory.com/{YourGuid}/{YourEZTInstanceType}/REST/Geocode/Notes:
- {YourGuid} → Your EasyTerritory GUID.
- {YourEZTInstanceType} → One of [DEV], [TEST], or [APP] (APP = Production).
Request Headers
- Media Types: “application/json”
Request Body
{
keyCustomer?: string;
keyBing?: string;
keyAzure?: string
defaultCountryCode?: string;
enableAddressFallback?: boolean;
addressList: string[],
}| Name | Required | Type | Description |
|---|---|---|---|
| keyCustomer | No | String | Unique identifier for caching and customer tracking. Can be any unique value. |
| keyBing | No | String | Bing Maps key. |
| keyAzure | No | String | Azure Maps key. |
| defaultCountryCode | No | String | Default country code used for geocoding. |
| enableAddressFallback | No | Boolean | If a geocode attempt fails, use street, city, and state as fallback inputs for subsequent attempts. |
| addressList | Yes | String[] | Array of address records to geocode. |
iGeocodeResult Response
{
addressStandardized?: string;
addressCorrected?: string;
addressLine?: string;
country?: string;
adminLevel1?: string;
adminLevel2?: string;
locality?: string;
postalCode?: string;
locationMerc?: { x: number, y: number };
location?: { lon: number, lat: number };
finalProvider?: string;
didFallback?: boolean;
quality?: eGeocodeQuality;
qualityString?: string;
timeStampUtc?: number;
msToComplete?: number;
shouldRetry?: boolean;
warning?: string;
error?: string;
}| Name | Description |
|---|---|
| addressStandardized | Standardized input address. |
| addressCorrected | Corrected geocoded address. |
| addressLine | Main street-level portion of the geocoded address. |
| country | Geocoded country. |
| adminLevel1 | Geocoded state. |
| adminLevel2 | Geocoded county. |
| locality | Geocoded city. |
| postalCode | Geocoded ZIP 5. |
| locationMerc | Geocoded location in spherical Mercator (Web Mercator, EPSG:3857). Values are x (easting) and y (northing) in meters. |
| location | Geocoded location as latitude and longitude (WGS84). Latitude is north–south; longitude is east–west. |
| finalProvider | Provider that produced the final geocode result (after any fallbacks or retries). |
| didFallback | Whether the result came from falling back to an alternate provider or method. |
| quality | Geocode quality/precision: failed, suboptimal, or optimal. |
| qualityString | Text representation of geocode quality for display or logging. |
| timeStampUtc | UTC timestamp when the geocode completed, in milliseconds since the Unix epoch. |
| msToComplete | Time taken to complete the geocode request, in milliseconds. |
| shouldRetry | Whether the client may safely retry the request (typically for transient failures). |
| warning | Warning message for non-fatal issues during geocoding. |
| error | Error message describing why the request failed, if applicable. |
Sample Request
POST /12345678-1234-1234-1234-123456789abc/APP/REST/Geocode/ HTTP/1.1
Host: apps.easyterritory.com
Content-Type: application/json
{
"keyAzure": "12345678910111213141516181920",
"defaultCountryCode": "US",
"enableAddressFallback": true,
"addressList": [
"400 S Monroe St, Tallahassee, FL 32399"
]
}Sample Response
{
"results": [
{
"addressStandardized": "400 S Monroe St, Tallahassee, FL 32399",
"addressCorrected": "400 S Monroe St, Tallahassee, FL 32399, United States",
"addressLine": "400 S Monroe St",
"country": "United States",
"adminLevel1": "Florida",
"adminLevel2": "Leon County",
"locality": "Tallahassee",
"postalCode": "32399",
"locationMerc": {
"x": -9382600.25,
"y": 3530700.75
},
"location": {
"lon": -84.2813,
"lat": 30.4381
},
"finalProvider": "AzureMaps",
"didFallback": false,
"quality": "optimal",
"qualityString": "Optimal",
"timeStampUtc": 1732118400000,
"msToComplete": 137,
"shouldRetry": false,
"warning": "",
"error": ""
}
],
"rowCount": 1,
"hasRowErrors": false,
"error": ""
}