Calling EasyTerritory Web Services from Third-party App

Some of our customers have asked how to integrate their applications with EasyTerritory through our web service endpoints. Perhaps you have an application which could benefit from EasyTerritory geocoding (converting a street address to a latitude/longitude location.) In other scenarios, you might want to access the underlying map services to do a spatial query. Regardless of which service you need to access, the following information will help you architect an approach.

The first question you have to ask is will my application be able to reside under the same domain as where EasyTerritory is deployed? If you are using our cloud-hosted version of EasyTerritory then the answer is “it cannot.” However, for on-prem deployments, this may be an option. If you can deploy your application to the same domain (and same protocol http or https,) then you will be able to implement an approach using client-side (in the browser) JavaScript. Otherwise, for cross-domain access, you will have to write a server-side proxy (like a c#/ashx HTTP handler.)

Whether your approach is client or server side, you must do the following:

1. Get a login token by calling the EasyTerritory login web service:
   1. The service endpoint is: https://yourdomain.com/APP/REST/Login/Login
   2. request.Method = “POST”;
   3. request.ContentType = “application/json”;
   4. Pass in a json authentication object {username: [service user name], password: [service password]}
   5. Retrieve a json object with a ‘token’ property and a token string value
2. Call an EasyTerritory web service (in this example, the geocoding service)
   1. The service endpoint is: https://yourdomain.com/APP/REST/Geocode
   2. request.Method = “POST”;
   3. request.ContentType = “application/json”;
   4. Set the http request cookie with the above login token: oitoken=[above token]
      (note: this will not work in a client-side scenario if you attempt to go cross-domain.)
   5. The json object to post in the case of geocoding:

       {
         keyCustomer: string;
         keyBing: string; // your Microsoft Bing key
         defaultCountryCode?: string; // e.g. US
         enableAddressFallback?: boolean; // whether or not to fallback to postal code on fail
         addressList: string[];
       }

   6. Note: properties with a ? are optional
   7. Note: keyCustomer is just a unique id (e.g. GUID) for use in caching and customer tracking (it should be your bing key.)
   8. The return json object:

       {
         results: iGeocodeResult[];
         rowCount?: number;
         hasRowErrors?: boolean;
         error?: string;
       }

   9. interface iGeocodeResult

       {
         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;
         warning?: string;
       }