aspernaturalias 1.0.0

package/packages/arcgis-rest-geocoding/src/bulk.ts

@@ -0,0 +1,105 @@
+/* Copyright (c) 2017-2018 Environmental Systems Research Institute, Inc.
+ * Apache-2.0 */
+
+import { request, cleanUrl } from "@esri/arcgis-rest-request";
+import { ISpatialReference, IPoint } from "@esri/arcgis-rest-types";
+
+import { ARCGIS_ONLINE_GEOCODING_URL, IEndpointOptions } from "./helpers";
+
+// it'd be better if doc didnt display these properties in alphabetical order
+export interface IAddressBulk {
+  /**
+   * A unique id must be passed along for each individual address.
+   */
+  OBJECTID: number;
+  address?: string;
+  address2?: string;
+  address3?: string;
+  neighborhood?: string;
+  city?: string;
+  subregion?: string;
+  /**
+   * The World Geocoding Service considers US states regions.
+   */
+  region?: string;
+  postal?: number;
+  postalExt?: number;
+  countryCode?: string;
+}
+
+export interface IBulkGeocodeOptions extends IEndpointOptions {
+  addresses: IAddressBulk[];
+}
+
+export interface IBulkGeocodeResponse {
+  spatialReference: ISpatialReference;
+  locations: Array<{
+    address: string;
+    location?: IPoint; // candidates with a score of 0 wont include a location
+    score: number;
+    attributes: object;
+  }>;
+}
+
+/**
+ * ```js
+ * import { bulkGeocode } from '@esri/arcgis-rest-geocoding';
+ * import { ApplicationSession } from '@esri/arcgis-rest-auth';
+ * //
+ * const addresses = [
+ *   { "OBJECTID": 1, "SingleLine": "380 New York Street 92373" },
+ *   { "OBJECTID": 2, "SingleLine": "1 World Way Los Angeles 90045" }
+ * ];
+ * //
+ * bulkGeocode({ addresses, authentication: session })
+ *   .then((response) => {
+ *     response.locations[0].location; // => { x: -117, y: 34, spatialReference: { wkid: 4326 } }
+ *   });
+ * ```
+ * Used to geocode a [batch](https://developers.arcgis.com/rest/geocode/api-reference/geocoding-geocode-addresses.htm) of addresses.
+ *
+ * @param requestOptions - Request options to pass to the geocoder, including an array of addresses and authentication session.
+ * @returns A Promise that will resolve with the data from the response. The spatial reference will be added to address locations unless `rawResponse: true` was passed.
+ */
+export function bulkGeocode(
+  requestOptions: IBulkGeocodeOptions // must POST, which is the default
+): Promise<IBulkGeocodeResponse> {
+  const options: IBulkGeocodeOptions = {
+    endpoint: ARCGIS_ONLINE_GEOCODING_URL,
+    params: {
+      forStorage: true,
+      addresses: { records: [] }
+    },
+    ...requestOptions
+  };
+
+  requestOptions.addresses.forEach(address => {
+    options.params.addresses.records.push({ attributes: address });
+  });
+
+  // the SAS service doesnt support anonymous requests
+  if (
+    !requestOptions.authentication &&
+    options.endpoint === ARCGIS_ONLINE_GEOCODING_URL
+  ) {
+    return Promise.reject(
+      "bulk geocoding using the ArcGIS service requires authentication"
+    );
+  }
+
+  return request(
+    `${cleanUrl(options.endpoint)}/geocodeAddresses`,
+    options
+  ).then(response => {
+    if (options.rawResponse) {
+      return response;
+    }
+    const sr = response.spatialReference;
+    response.locations.forEach(function(address: { location: IPoint }) {
+      if (address.location) {
+        address.location.spatialReference = sr;
+      }
+    });
+    return response;
+  });
+}

package/packages/arcgis-rest-geocoding/src/geocode.ts

@@ -0,0 +1,130 @@
+/* Copyright (c) 2017-2018 Environmental Systems Research Institute, Inc.
+ * Apache-2.0 */
+
+import {
+  request,
+  cleanUrl,
+  appendCustomParams
+} from "@esri/arcgis-rest-request";
+
+import { IExtent, ISpatialReference, IPoint } from "@esri/arcgis-rest-types";
+
+import { ARCGIS_ONLINE_GEOCODING_URL, IEndpointOptions } from "./helpers";
+
+export interface IGeocodeOptions extends IEndpointOptions {
+  /**
+   * use this if all your address info is contained in a single string.
+   */
+  singleLine?: string;
+  address?: string;
+  address2?: string;
+  address3?: string;
+  neighborhood?: string;
+  city?: string;
+  subregion?: string;
+  /**
+   * The World Geocoding Service expects US states to be passed in as a 'region'.
+   */
+  region?: string;
+  postal?: number;
+  postalExt?: number;
+  countryCode?: string;
+  /**
+   * 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-geocoding';
+   * suggest("LAX")
+   *   .then((response) => {
+   *     geocode({
+   *       singleLine: response.suggestions[1].text,
+   *       magicKey: response.suggestions[0].magicKey
+   *     })
+   *   })
+   * ```
+   */
+  magicKey?: string;
+}
+
+export interface IGeocodeResponse {
+  spatialReference: ISpatialReference;
+  candidates: Array<{
+    address: string;
+    location: IPoint;
+    extent?: IExtent;
+    score: number;
+    attributes: object;
+  }>;
+}
+
+/**
+ * ```js
+ * import { geocode } from '@esri/arcgis-rest-geocoding';
+ * //
+ * geocode("LAX")
+ *   .then((response) => {
+ *     response.candidates[0].location; // => { x: -118.409, y: 33.943, spatialReference: ...  }
+ *   });
+ * //
+ * geocode({
+ *   address: "1600 Pennsylvania Ave",
+ *   postal: 20500,
+ *   countryCode: "USA"
+ * })
+ *   .then((response) => {
+ *     response.candidates[1].location; // => { x: -77.036533, y: 38.898719, spatialReference: ... }
+ *   });
+ * ```
+ * Used to determine the location of a single address or point of interest. See the [REST Documentation](https://developers.arcgis.com/rest/geocode/api-reference/geocoding-find-address-candidates.htm) for more information.
+ * @param address String representing the address or point of interest or RequestOptions to pass to the endpoint.
+ * @returns A Promise that will resolve with address candidates for the request. The spatial reference will be added to candidate locations and extents unless `rawResponse: true` was passed.
+ */
+export function geocode(
+  address: string | IGeocodeOptions
+): Promise<IGeocodeResponse> {
+  let options: IGeocodeOptions = {};
+  let endpoint: string;
+
+  if (typeof address === "string") {
+    options.params = { singleLine: address };
+    endpoint = ARCGIS_ONLINE_GEOCODING_URL;
+  } else {
+    endpoint = address.endpoint || ARCGIS_ONLINE_GEOCODING_URL;
+    options = appendCustomParams<IGeocodeOptions>(
+      address,
+      [
+        "singleLine",
+        "address",
+        "address2",
+        "address3",
+        "neighborhood",
+        "city",
+        "subregion",
+        "region",
+        "postal",
+        "postalExt",
+        "countryCode"
+      ],
+      { params: { ...address.params } }
+    );
+  }
+
+  // add spatialReference property to individual matches
+  return request(`${cleanUrl(endpoint)}/findAddressCandidates`, options).then(
+    response => {
+      if (typeof address !== "string" && address.rawResponse) {
+        return response;
+      }
+      const sr = response.spatialReference;
+      response.candidates.forEach(function(candidate: {
+        location: IPoint;
+        extent?: IExtent;
+      }) {
+        candidate.location.spatialReference = sr;
+        if (candidate.extent) {
+          candidate.extent.spatialReference = sr;
+        }
+      });
+      return response;
+    }
+  );
+}

package/packages/arcgis-rest-geocoding/src/helpers.ts

@@ -0,0 +1,54 @@
+/* Copyright (c) 2017 Environmental Systems Research Institute, Inc.
+ * Apache-2.0 */
+
+import { request, IRequestOptions } from "@esri/arcgis-rest-request";
+
+// https always
+export const ARCGIS_ONLINE_GEOCODING_URL =
+  "https://geocode.arcgis.com/arcgis/rest/services/World/GeocodeServer/";
+
+// nice to have: verify custom endpoints contain 'GeocodeServer' and end in a '/'
+export interface IEndpointOptions extends IRequestOptions {
+  /**
+   * Any ArcGIS Geocoding service (example: http://sampleserver6.arcgisonline.com/arcgis/rest/services/Locators/SanDiego/GeocodeServer )
+   */
+  endpoint?: string;
+}
+
+export interface IGetGeocodeServiceResponse {
+  currentVersion: number;
+  serviceDescription: string;
+  addressFields: any[];
+  countries: string[];
+  capabilities: string;
+}
+
+/**
+ * Used to fetch metadata from a geocoding service.
+ *
+ * ```js
+ * import { getGeocoderServiceInfo } from '@esri/arcgis-rest-geocoding';
+ *
+ * getGeocoderServiceInfo()
+ *   .then((response) => {
+ *     response.serviceDescription; // => 'World Geocoder'
+ *   });
+ * ```
+ *
+ * @param requestOptions - Request options can contain a custom geocoding service to fetch metadata from.
+ * @returns A Promise that will resolve with the data from the response.
+ */
+export function getGeocodeService(
+  requestOptions?: IEndpointOptions
+): Promise<IGetGeocodeServiceResponse> {
+  const url =
+    (requestOptions && requestOptions.endpoint) || ARCGIS_ONLINE_GEOCODING_URL;
+
+  const options: IEndpointOptions = {
+    httpMethod: "GET",
+    maxUrlLength: 2000,
+    ...requestOptions
+  };
+
+  return request(url, options);
+}

package/packages/arcgis-rest-geocoding/src/index.ts

@@ -0,0 +1,15 @@
+/* Copyright (c) 2018 Environmental Systems Research Institute, Inc.
+ * Apache-2.0 */
+
+export * from "./geocode";
+export * from "./suggest";
+export * from "./reverse";
+export * from "./bulk";
+export * from "./helpers";
+
+export {
+  IPoint,
+  ILocation,
+  IExtent,
+  ISpatialReference
+} from "@esri/arcgis-rest-types";

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

@@ -0,0 +1,84 @@
+/* Copyright (c) 2017-2018 Environmental Systems Research Institute, Inc.
+ * Apache-2.0 */
+
+import { request, cleanUrl } from "@esri/arcgis-rest-request";
+
+import { IPoint, ILocation } from "@esri/arcgis-rest-types";
+
+import { ARCGIS_ONLINE_GEOCODING_URL, IEndpointOptions } from "./helpers";
+
+export interface IReverseGeocodeResponse {
+  address: {
+    [key: string]: any;
+  };
+  location: IPoint;
+}
+
+function isLocationArray(
+  coords: ILocation | IPoint | [number, number] | [number, number, number]
+): coords is [number, number] | [number, number, number] {
+  return (
+    (coords as [number, number]).length === 2 ||
+    (coords as [number, number, number]).length === 3
+  );
+}
+
+function isLocation(
+  coords: ILocation | IPoint | [number, number] | [number, number, number]
+): coords is ILocation {
+  return (
+    (coords as ILocation).latitude !== undefined ||
+    (coords as ILocation).lat !== undefined
+  );
+}
+
+/**
+ * ```js
+ * import { reverseGeocode } from '@esri/arcgis-rest-geocoding';
+ * //
+ * reverseGeocode([-118.409,33.943 ]) // long, lat
+ *   .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 })
+ * ```
+ * Used to determine the address of a [location](https://developers.arcgis.com/rest/geocode/api-reference/geocoding-reverse-geocode.htm).
+ *
+ * @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?: IEndpointOptions
+): Promise<IReverseGeocodeResponse> {
+  const options: IEndpointOptions = {
+    endpoint: ARCGIS_ONLINE_GEOCODING_URL,
+    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(`${cleanUrl(options.endpoint)}/reverseGeocode`, options);
+}
+
+export default {
+  reverseGeocode
+};

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

@@ -0,0 +1,45 @@
+/* Copyright (c) 2017-2018 Environmental Systems Research Institute, Inc.
+ * Apache-2.0 */
+
+import { request, cleanUrl } from "@esri/arcgis-rest-request";
+
+import { ARCGIS_ONLINE_GEOCODING_URL, IEndpointOptions } from "./helpers";
+
+export interface ISuggestResponse {
+  suggestions: Array<{
+    text: string;
+    magicKey: string;
+    isCollection: boolean;
+  }>;
+}
+
+/**
+ * ```js
+ * import { suggest } from '@esri/arcgis-rest-geocoding';
+ * //
+ * suggest("Starb")
+ *   .then(response) // response.text === "Starbucks"
+ * ```
+ * Used to return a placename [suggestion](https://developers.arcgis.com/rest/geocode/api-reference/geocoding-suggest.htm) for a partial string.
+ *
+ * @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?: IEndpointOptions
+): Promise<ISuggestResponse> {
+  const options: IEndpointOptions = {
+    endpoint: ARCGIS_ONLINE_GEOCODING_URL,
+    params: {},
+    ...requestOptions
+  };
+
+  options.params.text = partialText;
+
+  return request(`${cleanUrl(options.endpoint)}/suggest`, options);
+}
+
+export default {
+  suggest
+};

package/packages/arcgis-rest-geocoding/test/bulk.test.ts

@@ -0,0 +1,151 @@
+/* Copyright (c) 2018 Environmental Systems Research Institute, Inc.
+ * Apache-2.0 */
+
+import { bulkGeocode } from "../src/bulk";
+import { GeocodeAddresses } from "./mocks/responses";
+
+import * as fetchMock from "fetch-mock";
+
+const addresses = [
+  {
+    OBJECTID: 1,
+    SingleLine: "380 New York St. Redlands 92373"
+  },
+  {
+    OBJECTID: 2,
+    SingleLine: "1 World Way Los Angeles 90045"
+  },
+  {
+    OBJECTID: 3,
+    SingleLine: "foo bar baz"
+  }
+];
+
+describe("geocode", () => {
+  afterEach(fetchMock.restore);
+
+  it("should make a bulk geocoding request, even with an unmatchable record", 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"}},{"attributes":{"OBJECTID":3,"SingleLine":"foo bar baz"}}]}'
+          )}`
+        );
+        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
+        );
+        expect(response.locations[2].score).toEqual(0);
+        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"}},{"attributes":{"OBJECTID":3,"SingleLine":"foo bar baz"}}]}'
+          )}`
+        );
+        // 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
+        );
+        expect(response.locations[2].address).toEqual("foo bar baz");
+        done();
+      });
+  });
+
+  it("should support rawResponse", done => {
+    fetchMock.once("*", GeocodeAddresses);
+
+    const MOCK_AUTH = {
+      getToken() {
+        return Promise.resolve("token");
+      },
+      portal: "https://mapsdev.arcgis.com"
+    };
+
+    bulkGeocode({ addresses, authentication: MOCK_AUTH, rawResponse: true })
+      .then((response: any) => {
+        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(response.status).toBe(200);
+        expect(response.ok).toBe(true);
+        expect(response.body.Readable).not.toBe(null);
+        response.json().then((raw: any) => {
+          expect(raw).toEqual(GeocodeAddresses);
+          done();
+        });
+        // this used to work with isomorphic-fetch
+        // expect(response instanceof Response).toBe(true);
+      })
+      .catch(e => {
+        fail(e);
+      });
+  });
+});