ducimusipsa 1.0.0

package/packages/arcgis-rest-geocoder/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "@esri/arcgis-rest-geocoder",
+  "version": "1.14.1",
+  "description": "Geocoding helpers for @esri/arcgis-rest-request",
+  "main": "dist/node/index.js",
+  "browser": "dist/umd/geocoder.umd.js",
+  "module": "dist/esm/index.js",
+  "js:next": "dist/esm/index.js",
+  "types": "dist/esm/index.d.ts",
+  "license": "Apache-2.0",
+  "files": [
+    "dist/**"
+  ],
+  "dependencies": {
+    "tslib": "^1.7.1"
+  },
+  "devDependencies": {
+    "@esri/arcgis-rest-auth": "^1.14.1",
+    "@esri/arcgis-rest-common-types": "^1.14.1",
+    "@esri/arcgis-rest-request": "^1.14.1"
+  },
+  "peerDependencies": {
+    "@esri/arcgis-rest-auth": "^1.14.1",
+    "@esri/arcgis-rest-common-types": "^1.14.1",
+    "@esri/arcgis-rest-request": "^1.14.1"
+  },
+  "scripts": {
+    "prepare": "npm run build",
+    "build": "npm run build:node && npm run build:umd && npm run build:esm",
+    "build:esm": "tsc -p ./tsconfig.json --module es2015 --outDir ./dist/esm --declaration",
+    "build:umd": "rollup -c ../../umd-base-profile.js && rollup -c ../../umd-production-profile.js",
+    "build:node": "tsc -p ./tsconfig.json --module commonjs --outDir ./dist/node",
+    "dev:esm": "tsc -w --module es2015 --outDir ./dist/esm --declaration",
+    "dev:umd": "rollup -w -c ../../umd-base-profile.js",
+    "dev:node": "tsc -w --module commonjs --outDir ./dist/node"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Esri/arcgis-rest-js.git"
+  },
+  "contributors": [
+    {
+      "name": "Patrick Arlt",
+      "email": "parlt@esri.com",
+      "url": "http://patrickarlt.com/"
+    }
+  ],
+  "bugs": {
+    "url": "https://github.com/Esri/arcgis-rest-js/issues"
+  },
+  "homepage": "https://github.com/Esri/arcgis-rest-js#readme"
+}

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

@@ -0,0 +1,102 @@
+/* Copyright (c) 2017-2018 Environmental Systems Research Institute, Inc.
+ * Apache-2.0 */
+
+import { request } from "@esri/arcgis-rest-request";
+
+import { ISpatialReference, IPoint } from "@esri/arcgis-rest-common-types";
+
+import { worldGeocoder, IEndpointRequestOptions } 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 IBulkGeocodeRequestOptions extends IEndpointRequestOptions {
+  addresses: IAddressBulk[];
+}
+
+export interface IBulkGeocodeResponse {
+  spatialReference: ISpatialReference;
+  locations: Array<{
+    address: string;
+    location: IPoint;
+    score: number;
+    attributes: object;
+  }>;
+}
+
+/**
+ * Used to geocode a [batch](https://developers.arcgis.com/rest/geocode/api-reference/geocoding-geocode-addresses.htm) of addresses.
+ *
+ * ```js
+ * import { bulkGeocode } from '@esri/arcgis-rest-geocoder';
+ * 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 } }
+ *   });
+ * ```
+ *
+ * @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.
+ */
+export function bulkGeocode(
+  requestOptions: IBulkGeocodeRequestOptions // must POST
+) {
+  const options: IBulkGeocodeRequestOptions = {
+    endpoint: worldGeocoder,
+    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 === worldGeocoder) {
+    return Promise.reject(
+      "bulk geocoding using the ArcGIS service requires authentication"
+    );
+  }
+
+  return request(options.endpoint + "geocodeAddresses", options).then(
+    response => {
+      const sr = response.spatialReference;
+      response.locations.forEach(function(address: { location: IPoint }) {
+        address.location.spatialReference = sr;
+      });
+      return response;
+    }
+  );
+}
+
+export default {
+  bulkGeocode
+};

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

@@ -0,0 +1,130 @@
+/* Copyright (c) 2017-2018 Environmental Systems Research Institute, Inc.
+ * Apache-2.0 */
+
+import {
+  request,
+  IParams,
+  appendCustomParams
+} from "@esri/arcgis-rest-request";
+
+import {
+  IExtent,
+  ISpatialReference,
+  IPoint
+} from "@esri/arcgis-rest-common-types";
+
+import { worldGeocoder, IEndpointRequestOptions } from "./helpers";
+
+export interface IGeocodeParams extends IParams {
+  /**
+   * 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) => {
+   *     geocode({
+   *       singleLine: response.suggestions[1].text,
+   *       magicKey: response.suggestions[0].magicKey
+   *     })
+   *   })
+   * ```
+   */
+  magicKey?: string;
+}
+
+export interface IGeocodeRequestOptions extends IEndpointRequestOptions {
+  /**
+   * 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;
+}
+
+export interface IGeocodeResponse {
+  spatialReference: ISpatialReference;
+  candidates: Array<{
+    address: string;
+    location: IPoint;
+    extent?: IExtent;
+    score: number;
+    attributes: object;
+  }>;
+}
+
+/**
+ * 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.
+ *
+ * ```js
+ * import { geocode } from '@esri/arcgis-rest-geocoder';
+ *
+ * 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: ... }
+ *   });
+ * ```
+ *
+ * @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.
+ */
+export function geocode(
+  address: string | IGeocodeRequestOptions
+): Promise<IGeocodeResponse> {
+  let options: IGeocodeRequestOptions = {
+    endpoint: worldGeocoder,
+    params: {}
+  };
+
+  if (typeof address === "string") {
+    options.params.singleLine = address;
+  } else {
+    options.endpoint = address.endpoint || worldGeocoder;
+    options = {
+      ...options,
+      ...address
+    };
+
+    appendCustomParams(address, options);
+  }
+
+  // add spatialReference property to individual matches
+  return request(options.endpoint + "findAddressCandidates", options).then(
+    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;
+    }
+  );
+}
+
+export default {
+  geocode
+};

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

@@ -0,0 +1,80 @@
+/* Copyright (c) 2017 Environmental Systems Research Institute, Inc.
+ * Apache-2.0 */
+
+import { request, IRequestOptions, warn } from "@esri/arcgis-rest-request";
+
+// https always
+export const worldGeocoder =
+  "https://geocode.arcgis.com/arcgis/rest/services/World/GeocodeServer/";
+
+// to do: remove at v2.0.0 (and import from arcgis-rest-common instead)
+export interface ILocation {
+  latitude?: number;
+  longitude?: number;
+  lat?: number;
+  long?: number;
+}
+
+// nice to have: verify custom endpoints contain 'GeocodeServer' and end in a '/'
+export interface IEndpointRequestOptions 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-geocoder';
+ *
+ * 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?: IEndpointRequestOptions
+): Promise<IGetGeocodeServiceResponse> {
+  const url = (requestOptions && requestOptions.endpoint) || worldGeocoder;
+
+  const options: IEndpointRequestOptions = {
+    httpMethod: "GET",
+    maxUrlLength: 2000,
+    ...requestOptions
+  };
+
+  return request(url, options);
+}
+
+/**
+ * Deprecated. Please use [`getGeocodeService()`](../getGeocodeService/) instead.
+ *
+ * @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 serviceInfo(
+  requestOptions?: IEndpointRequestOptions
+): Promise<IGetGeocodeServiceResponse> {
+  warn(
+    "serviceInfo() will be deprecated in the next major release. please use getGeocoderServiceInfo() instead."
+  );
+  return getGeocodeService(requestOptions);
+}
+
+export default {
+  getGeocodeService
+};

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

@@ -0,0 +1,8 @@
+/* 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";

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

@@ -0,0 +1,83 @@
+/* Copyright (c) 2017-2018 Environmental Systems Research Institute, Inc.
+ * Apache-2.0 */
+
+import { request } from "@esri/arcgis-rest-request";
+import { IPoint } from "@esri/arcgis-rest-common-types";
+
+import { ILocation, worldGeocoder, IEndpointRequestOptions } from "./helpers";
+
+// to do: remove utility functions and import from arcgis-rest-common at v2
+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
+  );
+}
+
+export interface IReverseGeocodeResponse {
+  address: {
+    [key: string]: any;
+  };
+  location: IPoint;
+}
+
+/**
+ * Used to determine the address of a [location](https://developers.arcgis.com/rest/geocode/api-reference/geocoding-reverse-geocode.htm).
+ *
+ * ```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,69 @@
+/* Copyright (c) 2017-2018 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) => {
+   *     geocode({
+   *       singleLine: response.suggestions[1].text,
+   *       magicKey: response.suggestions[1].magicKey
+   *     })
+   *   })
+   * ```
+   */
+  magicKey?: string;
+}
+
+export interface ISuggestResponse {
+  suggestions: Array<{
+    text: string;
+    magicKey: string;
+    isCollection: boolean;
+  }>;
+}
+
+/**
+ * Used to return a placename [suggestion](https://developers.arcgis.com/rest/geocode/api-reference/geocoding-suggest.htm) for a partial string.
+ *
+ * ```js
+ * import { suggest } from '@esri/arcgis-rest-geocoder';
+ *
+ * suggest("Starb")
+ *   .then((response) => {
+ *     response.text; // => "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
+  };
+
+  options.params.text = partialText;
+
+  if (requestOptions && requestOptions.magicKey) {
+    options.params.magicKey = requestOptions.magicKey;
+  }
+
+  return request(options.endpoint + "suggest", options);
+}
+
+export default {
+  suggest
+};

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

@@ -0,0 +1,113 @@
+/* Copyright (c) 2018 Environmental Systems Research Institute, Inc.
+ * Apache-2.0 */
+
+import { bulkGeocode } from "../src/bulk";
+
+import * as fetchMock from "fetch-mock";
+
+import { GeocodeAddresses } from "./mocks/responses";
+
+const addresses = [
+  {
+    OBJECTID: 1,
+    SingleLine: "380 New York St. Redlands 92373"
+  },
+  {
+    OBJECTID: 2,
+    SingleLine: "1 World Way Los Angeles 90045"
+  }
+];
+
+describe("geocode", () => {
+  afterEach(fetchMock.restore);
+
+  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();
+      });
+  });
+});