sintfacilis 1.0.0

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

@@ -0,0 +1,66 @@
+{
+  "name": "@esri/arcgis-rest-geocoding",
+  "version": "3.3.0",
+  "description": "Geocoding helpers for @esri/arcgis-rest-js",
+  "main": "dist/node/index.js",
+  "unpkg": "dist/umd/geocoding.umd.js",
+  "module": "dist/esm/index.js",
+  "js:next": "dist/esm/index.js",
+  "sideEffects": false,
+  "types": "dist/esm/index.d.ts",
+  "license": "Apache-2.0",
+  "files": [
+    "dist/**"
+  ],
+  "dependencies": {
+    "@esri/arcgis-rest-types": "^3.3.0",
+    "@terraformer/arcgis": "^2.0.7",
+    "@types/terraformer__arcgis": "^2.0.0",
+    "tslib": "^1.13.0"
+  },
+  "devDependencies": {
+    "@esri/arcgis-rest-auth": "^3.3.0",
+    "@esri/arcgis-rest-request": "^3.3.0"
+  },
+  "peerDependencies": {
+    "@esri/arcgis-rest-auth": "^3.0.0",
+    "@esri/arcgis-rest-request": "^3.0.0"
+  },
+  "scripts": {
+    "prepare": "npm run build",
+    "build": "npm run build:node && npm run build:umd && npm run build:esm",
+    "build:esm": "tsc --module es2015 --outDir ./dist/esm --declaration",
+    "build:umd": "rollup -c ../../umd-base-profile.js && rollup -c ../../umd-production-profile.js",
+    "build:node": "tsc --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",
+    "directory": "packages/arcgis-rest-geocoding"
+  },
+  "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",
+  "keywords": [
+    "typescript",
+    "promise",
+    "fetch",
+    "arcgis",
+    "esri",
+    "ES6"
+  ]
+}

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

@@ -0,0 +1,104 @@
+/* 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_BULK_GEOCODING_URL, IEndpointOptions } from "./helpers";
+
+// It would be better if doc did not 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_BULK_GEOCODING_URL,
+    params: {},
+    ...requestOptions
+  };
+
+  options.params.addresses = {
+    records: requestOptions.addresses.map(address => {
+      return { attributes: address };
+    })
+  };
+
+  // the SAS service does not support anonymous requests
+  if (
+    !requestOptions.authentication &&
+    options.endpoint === ARCGIS_ONLINE_BULK_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,166 @@
+/* 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";
+
+import { arcgisToGeoJSON } from "@terraformer/arcgis";
+
+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;
+  outFields?: "*" | 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;
+  }>;
+  geoJson?: {
+    type: string;
+    features: Array<{
+      type: string;
+      geometry: object;
+      properties: any;
+    }>
+  };
+}
+
+/**
+ * ```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",
+        "outFields",
+        "magicKey"
+      ],
+      { 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: ISpatialReference = response.spatialReference;
+      response.candidates.forEach(function(candidate: {
+        location: IPoint;
+        extent?: IExtent;
+      }) {
+        candidate.location.spatialReference = sr;
+        if (candidate.extent) {
+          candidate.extent.spatialReference = sr;
+        }
+      });
+
+      // geoJson
+      if (sr.wkid === 4326) {
+        const features = response.candidates.map((candidate: any) => {
+          return {
+            type: "Feature",
+            geometry: arcgisToGeoJSON(candidate.location),
+            properties: Object.assign(
+              {
+                address: candidate.address,
+                score: candidate.score,
+              },
+              candidate.attributes
+            ),
+          };
+        });
+
+        response.geoJson = {
+          type: "FeatureCollection",
+          features,
+        };
+      }
+
+      return response;
+    }
+  );
+}

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

@@ -0,0 +1,56 @@
+/* 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-api.arcgis.com/arcgis/rest/services/World/GeocodeServer/";
+export const ARCGIS_ONLINE_BULK_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
+};