etincidunt 1.0.0

package/packages/arcgis-rest-geocoder/src/reverse.ts

@@ -0,0 +1,84 @@
+/* Copyright (c) 2017 Environmental Systems Research Institute, Inc.
+ * Apache-2.0 */
+
+import { request } from "@esri/arcgis-rest-request";
+
+import { IPoint } from "@esri/arcgis-rest-common-types";
+
+import { worldGeocoder, ILocation, IEndpointRequestOptions } from "./helpers";
+
+export interface IReverseGeocodeResponse {
+  address: {
+    [key: string]: any;
+  };
+  location: IPoint;
+}
+
+function isLocationArray(
+  coords: ILocation | IPoint | [number, number]
+): coords is [number, number] {
+  return (coords as [number, number]).length === 2;
+}
+
+function isLocation(
+  coords: ILocation | IPoint | [number, number]
+): coords is ILocation {
+  return (
+    (coords as ILocation).latitude !== undefined ||
+    (coords as ILocation).lat !== undefined
+  );
+}
+
+/**
+ * Used to determine the address of a location.
+ *
+ * ```js
+ * import { reverseGeocode } from '@esri/arcgis-rest-geocoder';
+ *
+ * // long, lat
+ * reverseGeocode([-118.409,33.943 ])
+ *   .then((response) => {
+ *     response.address.PlaceName; // => "LA Airport"
+ *   });
+ *
+ * // or
+ * reverseGeocode({ long: -118.409, lat: 33.943 })
+ * reverseGeocode({ latitude: 33.943, latitude: -118.409 })
+ * reverseGeocode({ x: -118.409, y: 33.9425 }) // wgs84 is assumed
+ * reverseGeocode({ x: -13181226, y: 4021085, spatialReference: { wkid: 3857 })
+ * ```
+ *
+ * @param coordinates - the location you'd like to associate an address with.
+ * @param requestOptions - Additional options for the request including authentication.
+ * @returns A Promise that will resolve with the data from the response.
+ */
+export function reverseGeocode(
+  coords: IPoint | ILocation | [number, number],
+  requestOptions?: IEndpointRequestOptions
+): Promise<IReverseGeocodeResponse> {
+  const options: IEndpointRequestOptions = {
+    endpoint: worldGeocoder,
+    params: {},
+    ...requestOptions
+  };
+
+  if (isLocationArray(coords)) {
+    options.params.location = coords.join();
+  } else if (isLocation(coords)) {
+    if (coords.lat) {
+      options.params.location = coords.long + "," + coords.lat;
+    }
+    if (coords.latitude) {
+      options.params.location = coords.longitude + "," + coords.latitude;
+    }
+  } else {
+    // if input is a point, we can pass it straight through, with or without a spatial reference
+    options.params.location = coords;
+  }
+
+  return request(options.endpoint + "reverseGeocode", options);
+}
+
+export default {
+  reverseGeocode
+};

package/packages/arcgis-rest-geocoder/src/suggest.ts

@@ -0,0 +1,72 @@
+/* Copyright (c) 2017 Environmental Systems Research Institute, Inc.
+ * Apache-2.0 */
+
+import { request } from "@esri/arcgis-rest-request";
+
+import { worldGeocoder, IEndpointRequestOptions } from "./helpers";
+
+export interface ISuggestRequestOptions extends IEndpointRequestOptions {
+  /**
+   * You can create an autocomplete experience by making a call to suggest with partial text and then passing through the magicKey and complete address that are returned to geocode.
+   * ```js
+   * import { suggest, geocode } from '@esri/arcgis-rest-geocoder';
+   * suggest("LAX")
+   *   .then((response) => {
+   *     response.suggestions[2].magicKey; // =>  "dHA9MCNsb2M9Mjk3ODc2MCNsbmc9MzMjcGw9ODkxNDg4I2xicz0xNDoxNDc4MTI1MA=="
+   *   });
+   * geocode("LAX, 1 World Way, Los Angeles, CA, 90045, USA", {magicKey: "dHA9MCN..."})
+   * ```
+   */
+  magicKey?: string;
+}
+
+export interface ISuggestResponse {
+  suggestions: Array<{
+    text: string;
+    magicKey: string;
+    isCollection: boolean;
+  }>;
+}
+
+/**
+ * Used to return a placename suggestion for a partial string
+ *
+ * ```js
+ * import { suggest } from '@esri/arcgis-rest-geocoder';
+ *
+ * suggest("Starb")
+ *   .then((response) => {
+ *     response.address.PlaceName; // => "Starbucks"
+ *   });
+ * ```
+ *
+ * @param requestOptions - Options for the request including authentication and other optional parameters.
+ * @returns A Promise that will resolve with the data from the response.
+ */
+export function suggest(
+  partialText: string,
+  requestOptions?: ISuggestRequestOptions
+): Promise<ISuggestResponse> {
+  const options: ISuggestRequestOptions = {
+    endpoint: worldGeocoder,
+    params: {},
+    ...requestOptions
+  };
+
+  // is this the most concise way to mixin these optional parameters?
+  if (requestOptions && requestOptions.params) {
+    options.params = requestOptions.params;
+  }
+
+  if (requestOptions && requestOptions.magicKey) {
+    options.params.magicKey = requestOptions.magicKey;
+  }
+
+  options.params.text = partialText;
+
+  return request(options.endpoint + "suggest", options);
+}
+
+export default {
+  suggest
+};

package/packages/arcgis-rest-geocoder/test/geocoder.test.ts

@@ -0,0 +1,510 @@
+import { geocode } from "../src/geocode";
+
+import { suggest } from "../src/suggest";
+
+import { reverseGeocode } from "../src/reverse";
+
+import { bulkGeocode } from "../src/bulk";
+
+import { serviceInfo, getGeocodeService } from "../src/helpers";
+
+import * as fetchMock from "fetch-mock";
+
+import {
+  FindAddressCandidates,
+  Suggest,
+  ReverseGeocode,
+  GeocodeAddresses,
+  SharingInfo
+} from "./mocks/responses";
+
+const addresses = [
+  {
+    OBJECTID: 1,
+    SingleLine: "380 New York St. Redlands 92373"
+  },
+  {
+    OBJECTID: 2,
+    SingleLine: "1 World Way Los Angeles 90045"
+  }
+];
+
+const customGeocoderUrl =
+  "https://foo.com/arcgis/rest/services/Custom/GeocodeServer/";
+
+describe("geocode", () => {
+  afterEach(fetchMock.restore);
+
+  it("should make a simple, single geocoding request", done => {
+    fetchMock.once("*", FindAddressCandidates);
+
+    geocode("LAX")
+      .then(response => {
+        expect(fetchMock.called()).toEqual(true);
+        const [url, options]: [string, RequestInit] = fetchMock.lastCall("*");
+        expect(url).toEqual(
+          "https://geocode.arcgis.com/arcgis/rest/services/World/GeocodeServer/findAddressCandidates"
+        );
+        expect(options.method).toBe("POST");
+        expect(options.body).toContain("f=json");
+        expect(options.body).toContain("singleLine=LAX");
+        // the only property this lib tacks on
+        expect(response.spatialReference.wkid).toEqual(4326);
+        done();
+      })
+      .catch(e => {
+        fail(e);
+      });
+  });
+
+  it("should make a simple, single geocoding request with a custom parameter", done => {
+    fetchMock.once("*", FindAddressCandidates);
+
+    geocode({ params: { singleLine: "LAX", countryCode: "USA" } })
+      .then(response => {
+        expect(fetchMock.called()).toEqual(true);
+        const [url, options]: [string, RequestInit] = fetchMock.lastCall("*");
+        expect(url).toEqual(
+          "https://geocode.arcgis.com/arcgis/rest/services/World/GeocodeServer/findAddressCandidates"
+        );
+        expect(options.method).toBe("POST");
+        expect(options.body).toContain("f=json");
+        expect(options.body).toContain("singleLine=LAX");
+        expect(options.body).toContain("countryCode=USA");
+        // the only property this lib tacks on
+        expect(response.spatialReference.wkid).toEqual(4326);
+        done();
+      })
+      .catch(e => {
+        fail(e);
+      });
+  });
+
+  it("should make a single geocoding request to a custom geocoding service", done => {
+    fetchMock.once("*", FindAddressCandidates);
+
+    geocode({
+      endpoint: customGeocoderUrl,
+      params: {
+        outSr: 3857,
+        address: "380 New York St",
+        postal: 92373
+      }
+    })
+      .then(response => {
+        expect(fetchMock.called()).toEqual(true);
+        const [url, options]: [string, RequestInit] = fetchMock.lastCall("*");
+        expect(url).toEqual(
+          "https://foo.com/arcgis/rest/services/Custom/GeocodeServer/findAddressCandidates"
+        );
+        expect(options.method).toBe("POST");
+        expect(options.body).toContain("f=json");
+        expect(options.body).toContain(
+          `address=${encodeURIComponent("380 New York St")}`
+        );
+        expect(options.body).toContain("postal=92373");
+        expect(options.body).toContain("outSr=3857");
+        // the only property this lib tacks on
+        expect(response.spatialReference.wkid).toEqual(4326);
+        done();
+      })
+      .catch(e => {
+        fail(e);
+      });
+  });
+
+  it("should pass through all requestOptions when making a geocoding request", done => {
+    fetchMock.once("*", FindAddressCandidates);
+
+    geocode({
+      endpoint: customGeocoderUrl,
+      params: {
+        outSr: 3857,
+        address: "380 New York St",
+        postal: 92373
+      },
+      httpMethod: "GET"
+    })
+      .then(response => {
+        expect(fetchMock.called()).toEqual(true);
+        const [url, options]: [string, RequestInit] = fetchMock.lastCall("*");
+        expect(url).toEqual(
+          "https://foo.com/arcgis/rest/services/Custom/GeocodeServer/findAddressCandidates?f=json&outSr=3857&address=380%20New%20York%20St&postal=92373"
+        );
+        expect(options.method).toBe("GET");
+        // the only property this lib tacks on
+        expect(response.spatialReference.wkid).toEqual(4326);
+        done();
+      })
+      .catch(e => {
+        fail(e);
+      });
+  });
+
+  it("should make a reverse geocoding request", done => {
+    fetchMock.once("*", ReverseGeocode);
+
+    reverseGeocode({ x: -118.409, y: 33.9425 })
+      .then(response => {
+        expect(fetchMock.called()).toEqual(true);
+        const [url, options]: [string, RequestInit] = fetchMock.lastCall("*");
+        expect(url).toEqual(
+          "https://geocode.arcgis.com/arcgis/rest/services/World/GeocodeServer/reverseGeocode"
+        );
+        expect(options.method).toBe("POST");
+        expect(options.body).toContain("f=json");
+        expect(options.body).toContain(
+          `location=${encodeURIComponent('{"x":-118.409,"y":33.9425}')}`
+        );
+        expect(response).toEqual(ReverseGeocode); // introspect the entire response
+        done();
+      })
+      .catch(e => {
+        fail(e);
+      });
+  });
+
+  it("should make a reverse geocoding GET request and pass through a spatial reference", done => {
+    fetchMock.once("*", ReverseGeocode);
+
+    reverseGeocode(
+      { x: -118.409, y: 33.9425, spatialReference: { wkid: 4326 } },
+      { httpMethod: "GET" }
+    )
+      .then(response => {
+        expect(fetchMock.called()).toEqual(true);
+        const [url, options]: [string, RequestInit] = fetchMock.lastCall("*");
+        expect(url).toEqual(
+          "https://geocode.arcgis.com/arcgis/rest/services/World/GeocodeServer/reverseGeocode?f=json&location=%7B%22x%22%3A-118.409%2C%22y%22%3A33.9425%2C%22spatialReference%22%3A%7B%22wkid%22%3A4326%7D%7D"
+        );
+        expect(options.method).toBe("GET");
+        expect(response).toEqual(ReverseGeocode); // this introspects the entire response
+        done();
+      })
+      .catch(e => {
+        fail(e);
+      });
+  });
+
+  it("should make a reverse geocoding request and translate lat/long JSON objects", done => {
+    fetchMock.once("*", ReverseGeocode);
+
+    reverseGeocode({ longitude: -118.409, latitude: 33.9425 })
+      .then(response => {
+        expect(fetchMock.called()).toEqual(true);
+        const [url, options]: [string, RequestInit] = fetchMock.lastCall("*");
+        expect(url).toEqual(
+          "https://geocode.arcgis.com/arcgis/rest/services/World/GeocodeServer/reverseGeocode"
+        );
+        expect(options.method).toBe("POST");
+        expect(options.body).toContain("f=json");
+        expect(options.body).toContain(
+          `location=${encodeURIComponent("-118.409,33.9425")}`
+        );
+        expect(response).toEqual(ReverseGeocode); // this introspects the entire response
+        done();
+      })
+      .catch(e => {
+        fail(e);
+      });
+  });
+
+  it("should make a reverse geocoding request and translate lat/long JSON abbreviated objects", done => {
+    fetchMock.once("*", ReverseGeocode);
+
+    reverseGeocode({ lat: 33.9425, long: -118.409 })
+      .then(response => {
+        expect(fetchMock.called()).toEqual(true);
+        const [url, options]: [string, RequestInit] = fetchMock.lastCall("*");
+        expect(url).toEqual(
+          "https://geocode.arcgis.com/arcgis/rest/services/World/GeocodeServer/reverseGeocode"
+        );
+        expect(options.method).toBe("POST");
+        expect(options.body).toContain("f=json");
+        expect(options.body).toContain(
+          `location=${encodeURIComponent("-118.409,33.9425")}`
+        );
+        expect(response).toEqual(ReverseGeocode); // this introspects the entire response
+        done();
+      })
+      .catch(e => {
+        fail(e);
+      });
+  });
+
+  it("should make a reverse geocoding request and translate a raw long,lat array", done => {
+    fetchMock.once("*", ReverseGeocode);
+
+    reverseGeocode([-118, 34])
+      .then(response => {
+        expect(fetchMock.called()).toEqual(true);
+        const [url, options]: [string, RequestInit] = fetchMock.lastCall("*");
+        expect(url).toEqual(
+          "https://geocode.arcgis.com/arcgis/rest/services/World/GeocodeServer/reverseGeocode"
+        );
+        expect(options.method).toBe("POST");
+        expect(options.body).toContain("f=json");
+        expect(options.body).toContain(
+          `location=${encodeURIComponent("-118,34")}`
+        );
+        expect(response).toEqual(ReverseGeocode); // this introspects the entire response
+        done();
+      })
+      .catch(e => {
+        fail(e);
+      });
+  });
+
+  it("should make a request for suggestions", done => {
+    fetchMock.once("*", Suggest);
+
+    suggest("LAX")
+      .then(response => {
+        expect(fetchMock.called()).toEqual(true);
+        const [url, options]: [string, RequestInit] = fetchMock.lastCall("*");
+        expect(url).toEqual(
+          "https://geocode.arcgis.com/arcgis/rest/services/World/GeocodeServer/suggest"
+        );
+        expect(options.method).toBe("POST");
+        expect(options.body).toContain("f=json");
+        expect(options.body).toContain("text=LAX");
+        expect(response).toEqual(Suggest); // this introspects the entire response
+        done();
+      })
+      .catch(e => {
+        fail(e);
+      });
+  });
+
+  it("should make a request for suggestions with magic key", done => {
+    fetchMock.once("*", Suggest);
+
+    suggest("LAX", { magicKey: "foo" })
+      .then(response => {
+        expect(fetchMock.called()).toEqual(true);
+        const [url, options]: [string, RequestInit] = fetchMock.lastCall("*");
+        expect(url).toEqual(
+          "https://geocode.arcgis.com/arcgis/rest/services/World/GeocodeServer/suggest"
+        );
+        expect(options.method).toBe("POST");
+        expect(options.body).toContain("f=json");
+        expect(options.body).toContain("text=LAX");
+        expect(options.body).toContain("magicKey=foo");
+        expect(response).toEqual(Suggest); // this introspects the entire response
+        done();
+      })
+      .catch(e => {
+        fail(e);
+      });
+  });
+
+  it("should make a request for suggestions with other parameters", done => {
+    fetchMock.once("*", Suggest);
+
+    suggest("LAX", { params: { category: "Address,Postal" } })
+      .then(response => {
+        expect(fetchMock.called()).toEqual(true);
+        const [url, options]: [string, RequestInit] = fetchMock.lastCall("*");
+        expect(url).toEqual(
+          "https://geocode.arcgis.com/arcgis/rest/services/World/GeocodeServer/suggest"
+        );
+        expect(options.method).toBe("POST");
+        expect(options.body).toContain("f=json");
+        expect(options.body).toContain("text=LAX");
+        expect(options.body).toContain("category=Address%2CPostal");
+        expect(response).toEqual(Suggest); // this introspects the entire response
+        done();
+      })
+      .catch(e => {
+        fail(e);
+      });
+  });
+
+  it("should make a bulk geocoding request", done => {
+    fetchMock.once("*", GeocodeAddresses);
+
+    const MOCK_AUTH = {
+      getToken() {
+        return Promise.resolve("token");
+      },
+      portal: "https://mapsdev.arcgis.com"
+    };
+
+    bulkGeocode({ addresses, authentication: MOCK_AUTH })
+      .then(response => {
+        expect(fetchMock.called()).toEqual(true);
+        const [url, options]: [string, RequestInit] = fetchMock.lastCall("*");
+        expect(url).toEqual(
+          "https://geocode.arcgis.com/arcgis/rest/services/World/GeocodeServer/geocodeAddresses"
+        );
+        expect(options.method).toBe("POST");
+        expect(options.body).toContain("f=json");
+        expect(options.body).toContain(
+          `addresses=${encodeURIComponent(
+            '{"records":[{"attributes":{"OBJECTID":1,"SingleLine":"380 New York St. Redlands 92373"}},{"attributes":{"OBJECTID":2,"SingleLine":"1 World Way Los Angeles 90045"}}]}'
+          )}`
+        );
+        expect(options.body).toContain("token=token");
+        expect(response.spatialReference.latestWkid).toEqual(4326);
+        expect(response.locations[0].address).toEqual(
+          "380 New York St, Redlands, California, 92373"
+        );
+        expect(response.locations[0].location.x).toEqual(-117.19567031799994);
+        // the only property this lib tacks on
+        expect(response.locations[0].location.spatialReference.wkid).toEqual(
+          4326
+        );
+        done();
+      })
+      .catch(e => {
+        fail(e);
+      });
+  });
+
+  it("should throw an error when a bulk geocoding request is made without a token", done => {
+    fetchMock.once("*", GeocodeAddresses);
+
+    bulkGeocode({ addresses })
+      // tslint:disable-next-line
+      .catch(e => {
+        expect(e).toEqual(
+          "bulk geocoding using the ArcGIS service requires authentication"
+        );
+        done();
+      });
+  });
+
+  it("should send a bulk geocoding request to a custom url without a token", done => {
+    fetchMock.once("*", GeocodeAddresses);
+
+    bulkGeocode({
+      addresses,
+      endpoint:
+        "https://customer.gov/arcgis/rest/services/CompositeGeocoder/GeocodeServer/"
+    })
+      // tslint:disable-next-line
+      .then(response => {
+        expect(fetchMock.called()).toEqual(true);
+        const [url, options]: [string, RequestInit] = fetchMock.lastCall("*");
+        expect(url).toEqual(
+          "https://customer.gov/arcgis/rest/services/CompositeGeocoder/GeocodeServer/geocodeAddresses"
+        );
+        expect(options.method).toBe("POST");
+        expect(options.body).toContain("f=json");
+        expect(options.body).toContain(
+          `addresses=${encodeURIComponent(
+            '{"records":[{"attributes":{"OBJECTID":1,"SingleLine":"380 New York St. Redlands 92373"}},{"attributes":{"OBJECTID":2,"SingleLine":"1 World Way Los Angeles 90045"}}]}'
+          )}`
+        );
+        // expect(options.body).toContain("token=token");
+        expect(response.spatialReference.latestWkid).toEqual(4326);
+        expect(response.locations[0].address).toEqual(
+          "380 New York St, Redlands, California, 92373"
+        );
+        expect(response.locations[0].location.x).toEqual(-117.19567031799994);
+        // the only property this lib tacks on
+        expect(response.locations[0].location.spatialReference.wkid).toEqual(
+          4326
+        );
+        done();
+      });
+  });
+
+  it("should retrieve metadata from the World Geocoding Service", done => {
+    fetchMock.once("*", SharingInfo);
+
+    getGeocodeService()
+      .then(response => {
+        expect(fetchMock.called()).toEqual(true);
+        const [url, options]: [string, RequestInit] = fetchMock.lastCall("*");
+        expect(url).toEqual(
+          "https://geocode.arcgis.com/arcgis/rest/services/World/GeocodeServer/?f=json"
+        );
+        expect(options.method).toBe("GET");
+        // expect(response).toEqual(SharingInfo); // need to fix something in order introspect the whole response
+        expect(response.currentVersion).toEqual(10.41);
+        expect(response.serviceDescription).toEqual(
+          "Sample geocoder for San Diego, California, USA"
+        );
+        done();
+      })
+      .catch(e => {
+        fail(e);
+      });
+  });
+
+  it("should make POST request for metadata from the World Geocoding Service", done => {
+    fetchMock.once("*", SharingInfo);
+
+    getGeocodeService({ httpMethod: "POST" })
+      .then(response => {
+        expect(fetchMock.called()).toEqual(true);
+        const [url, options]: [string, RequestInit] = fetchMock.lastCall("*");
+        expect(url).toEqual(
+          "https://geocode.arcgis.com/arcgis/rest/services/World/GeocodeServer/"
+        );
+        expect(options.method).toBe("POST");
+        expect(options.body).toContain("f=json");
+        // expect(paramsSpy).toHaveBeenCalledWith("f", "json");
+        // expect(response).toEqual(SharingInfo); // need to fix something in order introspect the whole response
+        expect(response.currentVersion).toEqual(10.41);
+        expect(response.serviceDescription).toEqual(
+          "Sample geocoder for San Diego, California, USA"
+        );
+        done();
+      })
+      .catch(e => {
+        fail(e);
+      });
+  });
+
+  it("should retrieve metadata from custom geocoding services", done => {
+    fetchMock.once("*", SharingInfo);
+
+    getGeocodeService({ endpoint: customGeocoderUrl })
+      .then(response => {
+        expect(fetchMock.called()).toEqual(true);
+        const [url, options]: [string, RequestInit] = fetchMock.lastCall("*");
+        expect(url).toEqual(
+          "https://foo.com/arcgis/rest/services/Custom/GeocodeServer/?f=json"
+        );
+        expect(options.method).toBe("GET");
+        // how to introspect the whole response?
+        // expect(response).toEqual(SharingInfo);
+        expect(response.currentVersion).toEqual(10.41);
+        expect(response.serviceDescription).toEqual(
+          "Sample geocoder for San Diego, California, USA"
+        );
+        done();
+      })
+      .catch(e => {
+        fail(e);
+      });
+  });
+
+  it("should retrieve metadata from the World Geocoding Service using the old method name", done => {
+    fetchMock.once("*", SharingInfo);
+
+    // intercept deprecation warning
+    console.warn = jasmine.createSpy("warning");
+
+    serviceInfo()
+      .then(response => {
+        expect(fetchMock.called()).toEqual(true);
+        const [url, options]: [string, RequestInit] = fetchMock.lastCall("*");
+        expect(url).toEqual(
+          "https://geocode.arcgis.com/arcgis/rest/services/World/GeocodeServer/?f=json"
+        );
+        expect(options.method).toBe("GET");
+        // expect(response).toEqual(SharingInfo); // need to fix something in order introspect the whole response
+        expect(response.currentVersion).toEqual(10.41);
+        expect(response.serviceDescription).toEqual(
+          "Sample geocoder for San Diego, California, USA"
+        );
+        done();
+      })
+      .catch(e => {
+        fail(e);
+      });
+  });
+});