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.www.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[],
}
Field
Required
Type
Description
keyCustomer
No
String
A unique identifier for use in caching and customer tracking (it can be any unique value).
keyBing
No
String
Bing Maps Key.
keyAzure
No
String
Azure Maps Key.
defaultCountryCode
No
String
Country code to use as the default country for geocoding.
enableAddressFallback
No
Boolean
If a geocode attempt fails, the system will use the street, city, and state values as fallback inputs for any subsequent geocode attempts.
addressList
Yes
String[]
An array of address records to be geocoded.
Response Body
{
results: iGeocodeResult[];
rowCount: number;
hasRowErrors: boolean;
error: string;
}
Field
Description
results
iGeocodeResult[]
rowCount
The number of rows returned in the response.
hasRowErrors
Indicates whether any row contains an error.
error
A message describing the error, if one occurred.
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;
}
Field
Description
addressStandardized
Standardized input address.
addressCorrected
The 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 expressed in spherical Mercator (Web Mercator, EPSG:3857) projection coordinates. Values represent x (easting) and y (northing) positions in meters.
location
Geocoded location represented as latitude and longitude (WGS84). Latitude indicates the north–south position, and longitude indicates the east–west position.
finalProvider
Name of the provider that produced the final geocode result (after any fallbacks or retries).
didFallback
Indicates whether the result was obtained by falling back to an alternate provider or method.
quality
Enum value indicating the quality/precision of the geocode result: failed, suboptimal, optimal
qualityString
Text representation of the geocode quality for display or logging.
timeStampUtc
UTC timestamp (in milliseconds since Unix epoch) when the geocode operation completed.
msToComplete
Total time, in milliseconds, taken to complete the geocode request.
shouldRetry
Indicates whether the client may safely retry the geocode request, typically when the failure is transient.
warning
Warning message describing non-fatal issues encountered during the geocode operation.
error
Error message describing why the geocode request failed, if applicable.
Sample Request
cURL
Sample Response
JSON
{
“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”: “”
}
