autculpa 1.0.0

package/packages/arcgis-rest-demographics/src/getAvailableCountries.ts

@@ -0,0 +1,113 @@
+/* Copyright (c) 2020 Environmental Systems Research Institute, Inc.
+ * Apache-2.0 */
+
+import {
+  request,
+  cleanUrl,
+  appendCustomParams,
+  IExtent
+} from "@esri/arcgis-rest-request";
+
+
+import {
+  ARCGIS_ONLINE_GEOENRICHMENT_URL,
+  IEndpointOptions
+} from "./helpers.js";
+
+export interface IGetAvailableCountriesOptions extends IEndpointOptions {
+  /**
+   * View a description for a given country. If not specified, will return a list of all countries.
+   */
+  countryCode?: string;
+}
+
+export interface IGetAvailableCountriesResponse {
+  messages?: string[];
+  countries?: ICountry[];
+  childResources?: any[];
+}
+export interface ICountry {
+  id: string;
+  name: string;
+  abbr3: string;
+  altName: string;
+  continent: string;
+  distanceUnits: string;
+  esriUnits: string;
+  defaultExtent: IExtent;
+  defaultDatasetID: string;
+  datasets?: string[];
+  hierarchies?: IHierarchy[];
+  defaultDataCollection: string;
+  dataCollections: string;
+  defaultReportTemplate: string;
+  currencySymbol: string;
+  currencyFormat: string;
+}
+export interface IHierarchy {
+  ID: string;
+  alias: string;
+  shortDescription: string;
+  default: boolean;
+  longDescription: string;
+  locales?: string[];
+  datasets?: string[];
+  levelsInfo: ILevelsInfo;
+  variablesInfo: IVariablesInfo;
+  populationToPolygonSizeRating: number;
+  apportionmentConfidence: number;
+  apportionmentThresholds?: IApportionmentThreshold[];
+  hasMarginOfErrorData?: boolean;
+}
+export interface ILevelsInfo {
+  geographyLevels?: string[];
+}
+export interface IVariablesInfo {
+  categories?: string[];
+}
+export interface IApportionmentThreshold {
+  method: string;
+  dataLayer: string;
+  pointsLayer?: string;
+  maximumSize?: number;
+}
+
+/**
+ * ```js
+ * import { getAvailableCountries } from '@esri/arcgis-rest-demographics';
+ * //
+ * getAvailableCountries()
+ *   .then((response) => {
+ *     response; // => { countries: [ ... ]  }
+ *   });
+ * ```
+ * Return a list of information for all countries. See the [REST Documentation](https://developers.arcgis.com/rest/geoenrichment/api-reference/countries.htm) for more information.
+ * @param requestOptions Options to pass through to the geoenrichment service.
+ * @returns A Promise that will resolve with available geography levels for the request.
+ */
+export function getAvailableCountries(
+  requestOptions?: IGetAvailableCountriesOptions
+): Promise<IGetAvailableCountriesResponse> {
+  let options: IEndpointOptions = {};
+  let endpoint = `${ARCGIS_ONLINE_GEOENRICHMENT_URL}/countries`;
+  if (!requestOptions) {
+    options.params = {};
+  } else {
+    if (requestOptions.endpoint) {
+      endpoint = `${requestOptions.endpoint}/countries`;
+    }
+
+    options = appendCustomParams<IGetAvailableCountriesOptions>(
+      requestOptions,
+      [],
+      { params: { ...requestOptions.params } }
+    );
+    if (requestOptions.countryCode) {
+      endpoint = `${endpoint}/${requestOptions.countryCode}`;
+    }
+  }
+
+  return request(cleanUrl(endpoint), options).then((response: any) => {
+    return response;
+  });
+}

package/packages/arcgis-rest-demographics/src/getAvailableDataCollections.ts

@@ -0,0 +1,161 @@
+/* Copyright (c) 2020 Environmental Systems Research Institute, Inc.
+ * Apache-2.0 */
+
+import {
+  request,
+  cleanUrl,
+  appendCustomParams
+} from "@esri/arcgis-rest-request";
+
+import {
+  ARCGIS_ONLINE_GEOENRICHMENT_URL,
+  IEndpointOptions
+} from "./helpers.js";
+
+export interface IGetAvailableDataCollectionsOptions extends IEndpointOptions {
+  /**
+   * Optional parameter to specify an array of string values that describe what derivative variables to include in the output.
+   */
+  addDerivativeVariables?: string[];
+  /**
+   * Optional parameter to return only values that are not NULL in the output response.
+   */
+  suppressNullValues?: boolean;
+  /**
+   * View a description for a single data collection within a given country. If not specified, will return a list of data collections that can be run in any country.
+   */
+  countryCode?: string;
+  dataCollection?: string;
+}
+
+export interface IGetAvailableDataCollectionsResponse {
+  DataCollections?: IDataCollection[] | null;
+}
+export interface IDataCollection {
+  dataCollectionID: string;
+  metadata: IMetadata;
+  data?: IDataInfo[] | null;
+}
+export interface IMetadata {
+  title: string;
+  name: string;
+  shortDescription: string;
+  longDescription: string;
+  url: string;
+  keywords: string;
+  creationDate: number;
+  lastRevisionDate: number;
+  webmap: string;
+  author: string;
+  countries?: string | null;
+  IsRoyalties: boolean;
+  categories?: ICategory[] | null;
+  filters?: IFilter[] | null;
+  datasets?: string | null;
+  hierarchies: string;
+  coverage?: string | null;
+  mobileinfographics?: string | null;
+  icon?: string | null;
+}
+export interface ICategory {
+  id: string;
+  name: string;
+  alias: string;
+  description: string;
+  displayOrder: string;
+}
+export interface IFilter {
+  id: string;
+  name: string;
+  aliasname: string;
+  type: string;
+  rangeMax?: string | null;
+  rangeMin?: string | null;
+  enumValues?: string | null;
+}
+export interface IDataInfo {
+  id: string;
+  alias: string;
+  type: string;
+  precision: number;
+  length?: null;
+  averageBase?: null;
+  averageBaseAlias?: null;
+  description: string;
+  fieldCategory: string;
+  indexBase?: number | null;
+  percentBase?: string | null;
+  percentBaseAlias?: string | null;
+  popularity?: number | null;
+  units: string;
+  vintage?: string | null;
+  hideInDataBrowser: boolean;
+  filteringTags?: IFilteringTag[] | null;
+  derivative: boolean;
+  provider: string;
+  indexType?: string | null;
+}
+export interface IFilteringTag {
+  id: string;
+  name: string;
+  value: string;
+}
+
+/**
+ * ```js
+ * import { getAvailableDataCollections } from '@esri/arcgis-rest-demographics';
+ * //
+ * getAvailableDataCollections()
+ *   .then((response) => {
+ *     response; // => { DataCollections: [ ... ]  }
+ *   });
+ * //
+ * getAvailableDataCollections({
+ *   countryCode: "se",
+ *   dataCollection: "EducationalAttainment"
+ * })
+ *   .then((response) => {
+ *     response.; // => { DataCollections: [ ... ] }
+ *   });
+ * ```
+ * Used to determine the data collections available for usage with the Geoenrichment service. See the [REST Documentation](https://developers.arcgis.com/rest/geoenrichment/api-reference/data-collections.htm) for more information.
+ * @param requestOptions Options to pass through to the geoenrichment service.
+ * @returns A Promise that will resolve with data collections for the request.
+ */
+export function getAvailableDataCollections(
+  requestOptions?: IGetAvailableDataCollectionsOptions
+): Promise<IGetAvailableDataCollectionsResponse> {
+  let options: IGetAvailableDataCollectionsOptions = {};
+  let endpoint = `${ARCGIS_ONLINE_GEOENRICHMENT_URL}/dataCollections`;
+
+  if (!requestOptions) {
+    options.params = {};
+  } else {
+    if (requestOptions.endpoint) {
+      endpoint = `${requestOptions.endpoint}/dataCollections`;
+    }
+    options = appendCustomParams<IGetAvailableDataCollectionsOptions>(
+      requestOptions,
+      ["addDerivativeVariables", "suppressNullValues"],
+      { params: { ...requestOptions.params } }
+    );
+
+    if (options.params.addDerivativeVariables) {
+      options.params.addDerivativeVariables = JSON.stringify(
+        options.params.addDerivativeVariables
+      );
+    }
+
+    if (requestOptions.countryCode) {
+      endpoint = `${endpoint}/${requestOptions.countryCode}`;
+      if (requestOptions.dataCollection) {
+        endpoint = `${endpoint}/${requestOptions.dataCollection}`;
+      }
+    }
+  }
+
+  // add spatialReference property to individual matches
+  return request(`${cleanUrl(endpoint)}`, options).then((response: any) => {
+    return response;
+  });
+}

package/packages/arcgis-rest-demographics/src/getAvailableGeographyLevels.ts

@@ -0,0 +1,86 @@
+/* Copyright (c) 2020 Environmental Systems Research Institute, Inc.
+ * Apache-2.0 */
+
+import {
+  request,
+  cleanUrl,
+  appendCustomParams
+} from "@esri/arcgis-rest-request";
+
+import {
+  ARCGIS_ONLINE_GEOENRICHMENT_URL,
+  IEndpointOptions
+} from "./helpers.js";
+
+export interface IGetAvailableGeographyLevelsResponse {
+  messages?: string[] | null;
+  childResources?: any[] | null;
+  childDatasets?: any[] | null;
+  childHierarchies?: any[] | null;
+  geographyLevels?: IGeographyLevel[] | null;
+}
+export interface IGeographyLevel {
+  countryID: string;
+  countryName: string;
+  datasets?: IDataset[] | null;
+  hierarchies?: IGeographyLevelHierarchy[] | null;
+}
+export interface IDataset {
+  datasetID: string;
+  branches?: IBranch[] | null;
+  levels?: ILevel[] | null;
+}
+export interface IBranch {
+  id: string;
+  name: string;
+  levels?: string[] | null;
+}
+export interface ILevel {
+  id: string;
+  name: string;
+  isWholeCountry: boolean;
+  adminLevel: string;
+  singularName: string;
+  pluralName: string;
+  description?: string | null;
+}
+export interface IGeographyLevelHierarchy {
+  ID: string;
+  branches?: IBranch[] | null;
+  levels?: ILevel[] | null;
+}
+
+/**
+ * ```js
+ * import { getAvailableGeographyLevels } from '@esri/arcgis-rest-demographics';
+ * //
+ * getAvailableGeographyLevels()
+ *   .then((response) => {
+ *     response; // => { geographyLevels: [ ... ]  }
+ *   });
+ * ```
+ * Returns a list of available geography data layers, which can then be used in [getGeography()](). See the [REST Documentation](https://developers.arcgis.com/rest/geoenrichment/api-reference/standard-geography-levels.htm) for more information.
+ * @param requestOptions Options to pass through to the geoenrichment service.
+ * @returns A Promise that will resolve with available geography levels for the request.
+ */
+export function getAvailableGeographyLevels(
+  requestOptions?: IEndpointOptions
+): Promise<IGetAvailableGeographyLevelsResponse> {
+  let options: IEndpointOptions = {};
+  let endpoint = `${ARCGIS_ONLINE_GEOENRICHMENT_URL}/StandardGeographyLevels`;
+
+  if (!requestOptions) {
+    options.params = {};
+  } else {
+    if (requestOptions.endpoint) {
+      endpoint = `${requestOptions.endpoint}/StandardGeographyLevels`;
+    }
+    options = appendCustomParams<IEndpointOptions>(requestOptions, [], {
+      params: { ...requestOptions.params }
+    });
+  }
+
+  return request(`${cleanUrl(endpoint)}`, options).then((response: any) => {
+    return response;
+  });
+}

package/packages/arcgis-rest-demographics/src/getGeography.ts

@@ -0,0 +1,152 @@
+/* Copyright (c) 2020 Environmental Systems Research Institute, Inc.
+ * Apache-2.0 */
+
+import {
+  request,
+  cleanUrl,
+  appendCustomParams
+} from "@esri/arcgis-rest-request";
+
+import {
+  ARCGIS_ONLINE_STANDARD_GEOGRAPHY_QUERY_URL,
+  IGeoenrichmentResult,
+  IEndpointOptions
+} from "./helpers.js";
+
+export interface IGetGeographyOptions extends IEndpointOptions {
+  /**
+   * Specify the source country for the search.
+   */
+  sourceCountry?: string;
+  /**
+   * Specify a specific dataset within a defined country.
+   */
+  optionalCountryDataset?: string;
+  /**
+   * Specify which standard geography layers are being queried or searched.
+   */
+  geographyLayers?: string[] | string;
+  /**
+   * Specify which IDs for the standard geography layers are being queried or searched.
+   */
+  geographyIDs?: string[];
+  /**
+   * Specify the text to query and search the standard geography layers specified.
+   */
+  geographyQuery?: string;
+  /**
+   * Return all the subgeographic areas that are within a parent geography.
+   */
+  returnSubGeographyLayer?: boolean;
+  /**
+   * Return all the subgeographic areas that are within a parent geography.
+   */
+  subGeographyLayer?: string;
+  /**
+   * Filter the results of the subgeography features that are returned by a search term.
+   */
+  subGeographyQuery?: string;
+  /**
+   * Request the output geometries in a specified spatial reference system.
+   */
+  outSR?: number;
+  /**
+   * Request the output geometries in the response.
+   */
+  returnGeometry?: boolean;
+  /**
+   * Request the output geometry to return the center point for each feature.
+   */
+  returnCentroids?: boolean;
+  /**
+   * Integer that specifies the level of generalization or detail in the area representations of the administrative boundary or standard geographic data layers.
+   */
+  generalizationLevel?: number;
+  /**
+   * Define if text provided in the geographyQuery parameter should utilize fuzzy search logic.
+   */
+  useFuzzySearch?: boolean;
+  /**
+   * Limits the number of features that are returned from the geographyQuery parameter.
+   */
+  featureLimit?: number;
+  /**
+   * Starts the results on the number of the records specified.
+   */
+  featureOffset?: number;
+  /**
+   * Specifies the language you wish to receive your GeoEnrichment results.
+   */
+  langCode?: string;
+}
+
+export interface IGetGeographyResponse {
+  results: IGeoenrichmentResult[] | null;
+  messages: string[] | null;
+}
+
+/**
+ * ```js
+ * import { getGeography } from '@esri/arcgis-rest-demographics';
+ * //
+ * getGeography({
+ *   sourceCountry: "CA",
+ *   geographyIDs: ["35"]
+ * })
+ *   .then((response) => {
+ *     response.; // => { results: [ ... ] }
+ *   });
+ * ```
+ * Used to get standard geography IDs and features for the supported geographic levels. See the [REST Documentation](https://developers.arcgis.com/rest/geoenrichment/api-reference/standard-geography-query.htm) and the [best practices post](https://www.esri.com/arcgis-blog/products/arcgis-online/uncategorized/best-practices-how-to-query-standard-geographies-branches) for more information.
+ * @param requestOptions Options to pass through to the service. All properties are optional, but either `geographyIds` or `geographyQuery` must be sent at a minimum.
+ * @returns A Promise that will resolve with return data defined and optionally geometry for the feature.
+ */
+export function getGeography(
+  requestOptions?: IGetGeographyOptions
+): Promise<IGetGeographyResponse> {
+  const endpoint = `${
+    requestOptions.endpoint || ARCGIS_ONLINE_STANDARD_GEOGRAPHY_QUERY_URL
+  }/execute`;
+
+  const options = appendCustomParams<IGetGeographyOptions>(
+    requestOptions,
+    [
+      "sourceCountry",
+      "optionalCountryDataset",
+      "geographyLayers",
+      "geographyIDs",
+      "geographyQuery",
+      "returnSubGeographyLayer",
+      "subGeographyLayer",
+      "subGeographyQuery",
+      "outSR",
+      "returnGeometry",
+      "returnCentroids",
+      "generalizationLevel",
+      "useFuzzySearch",
+      "featureLimit",
+      "featureOffset",
+      "langCode"
+    ],
+    { params: { ...requestOptions.params } }
+  );
+
+  // the SAAS service does not support anonymous requests
+  if (!requestOptions.authentication) {
+    return Promise.reject(
+      "Geoenrichment using the ArcGIS service requires authentication"
+    );
+  }
+
+  // These parameters are passed as JSON-style strings:
+  ["geographyLayers", "geographyIDs"].forEach((parameter) => {
+    if (options.params[parameter]) {
+      options.params[parameter] = JSON.stringify(options.params[parameter]);
+    }
+  });
+
+  // add spatialReference property to individual matches
+  return request(`${cleanUrl(endpoint)}`, options).then((response: any) => {
+    return response;
+  });
+}

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

@@ -0,0 +1,27 @@
+/* Copyright (c) 2020 Environmental Systems Research Institute, Inc.
+ * Apache-2.0 */
+
+import {
+  IRequestOptions,
+  IFeatureSet
+} from "@esri/arcgis-rest-request";
+
+const ARCGIS_ONLINE_GEOENRICHMENTSERVER_URL = "https://geoenrich.arcgis.com/arcgis/rest/services/World/geoenrichmentserver"
+export const ARCGIS_ONLINE_GEOENRICHMENT_URL = `${ARCGIS_ONLINE_GEOENRICHMENTSERVER_URL}/Geoenrichment`;
+export const ARCGIS_ONLINE_STANDARD_GEOGRAPHY_QUERY_URL = `${ARCGIS_ONLINE_GEOENRICHMENTSERVER_URL}/StandardGeographyQuery`;
+
+export interface IEndpointOptions extends IRequestOptions {
+  /**
+   * Any ArcGIS Geoenrichment service (example: https://geoenrich.arcgis.com/arcgis/rest/services/World/geoenrichmentserver/Geoenrichment )
+   */
+  endpoint?: string;
+}
+
+export interface IGeoenrichmentResult {
+  paramName: string;
+  dataType: string;
+  value: {
+    version: string;
+    FeatureSet: IFeatureSet[];
+  };
+}

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

@@ -0,0 +1,16 @@
+/* Copyright (c) 2020 Environmental Systems Research Institute, Inc.
+ * Apache-2.0 */
+
+export * from "./getAvailableCountries.js";
+export * from "./getAvailableDataCollections.js";
+export * from "./getAvailableGeographyLevels.js";
+export * from "./getGeography.js";
+export * from "./queryDemographicData.js";
+
+// Types that are used in this package are re-exported for convenience and 
+// to make the links work correctly in the documentation pages.
+export type {
+  IRequestOptions,
+  IFeatureSet,
+  IExtent
+} from "@esri/arcgis-rest-request";

package/packages/arcgis-rest-demographics/src/queryDemographicData.ts

@@ -0,0 +1,108 @@
+/* Copyright (c) 2020 Environmental Systems Research Institute, Inc.
+ * Apache-2.0 */
+
+import {
+  request,
+  cleanUrl,
+  appendCustomParams
+} from "@esri/arcgis-rest-request";
+
+import {
+  ARCGIS_ONLINE_GEOENRICHMENT_URL,
+  IGeoenrichmentResult,
+  IEndpointOptions
+} from "./helpers.js";
+
+export interface IQueryDemographicDataOptions extends IEndpointOptions {
+  /**
+   * Defines the area on a map which is being analyzed
+   */
+  studyAreas: any[];
+  /**
+   * A Data Collection is a preassembled list of attributes that will be used to enrich the input features. Enrichment attributes can describe various types of information such as demographic characteristics and geographic context of the locations or areas submitted as input features in studyAreas.
+   */
+  dataCollections?: string[];
+  /**
+   * Specify a subset of variables to be returned from one or more Data Collections
+   */
+  analysisVariables?: string[];
+  /**
+   * Specify an array of string values that describe what derivative variables to include in the output
+   */
+  addDerivativeVariables?: boolean;
+  /**
+   * Request the output geometries in the response
+   */
+  returnGeometry?: boolean;
+  /**
+   * Define the input geometries in the studyAreas parameter in a specified spatial reference system
+   */
+  inSR?: number;
+  /**
+   * Request the output geometries in a specified spatial reference system
+   */
+  outSR?: number;
+}
+
+export interface IQueryDemographicDataResponse {
+  results: IGeoenrichmentResult[] | null;
+  messages: string[] | null;
+}
+
+/**
+ * ```js
+ * import { queryDemographicData } from '@esri/arcgis-rest-demographics';
+ * //
+ * queryDemographicData({
+ *  studyAreas: [{"geometry":{"x":-117.1956,"y":34.0572}}],
+ *  authentication
+ * })
+ *   .then((response) => {
+ *     response; // => { results: [ ... ] }
+ *   });
+ * ```
+ * Used to get facts about a location or area. See the [REST Documentation](https://developers.arcgis.com/rest/geoenrichment/api-reference/enrich.htm) for more information.
+ * @param requestOptions Options to pass through to the service.
+ * @returns A Promise that will resolve with results for the request.
+ */
+export function queryDemographicData(
+  requestOptions?: IQueryDemographicDataOptions
+): Promise<IQueryDemographicDataResponse> {
+  const options = appendCustomParams<IQueryDemographicDataOptions>(
+    requestOptions,
+    [
+      "studyAreas",
+      "dataCollections",
+      "analysisVariables",
+      "addDerivativeVariables",
+      "returnGeometry",
+      "inSR",
+      "outSR"
+    ],
+    { params: { ...requestOptions.params } }
+  );
+
+  // the SAAS service does not support anonymous requests
+  if (!requestOptions.authentication) {
+    return Promise.reject(
+      "Geoenrichment using the ArcGIS service requires authentication"
+    );
+  }
+
+  // These parameters are passed as JSON-style strings:
+  ["dataCollections", "analysisVariables"].forEach((parameter) => {
+    if (options.params[parameter]) {
+      options.params[parameter] = JSON.stringify(options.params[parameter]);
+    }
+  });
+
+  // add spatialReference property to individual matches
+  return request(
+    `${cleanUrl(
+      `${requestOptions.endpoint || ARCGIS_ONLINE_GEOENRICHMENT_URL}/enrich`
+    )}`,
+    options
+  ).then((response: any) => {
+    return response;
+  });
+}