---
title: Geocode Service
description: "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…"
url: "https://www.easyterritory.com/documentation/easyterritory-rest-api/call-easyterritory-geocoding-web-service/"
updated: "2026-11-09"
category: REST API
---

# Geocode Service

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. Provide **keyBing** or **keyAzure** (one provider key required). |
| keyAzure | No\* | String | Azure Maps key. Provide **keyAzure** or **keyBing** (one provider key required). |
| 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": ""}
```