FRAMES | NO FRAMES

 

B U S I N E S S   A N A L Y S T   10.2   R E S T   T R A D E   A R E A   T A S K

Standard Levels of Geography Endpoint

Generates trade areas based on standard geographic units.

 

Availability: Business Analyst Server.

 

URL Example

http://localhost:6080/arcgis/rest/services/DefaultMap/MapServer/exts/BAServer/StandardLevelsOfGeography/execute

Specific Parameters

Parameter

Description

GeographyLevelID (required)

ID of a geography level to get standard geographic units from. Type string.

AppendFields (optional)

An option specifying whether append the DataTable fields to the output trade area layer or not. Type boolean.

Default: false.

DataTable (optional)

Data table containing IDs of the geography level to be exported to the output trade area layer. Type TableData.

GeographyFeaturesBehavior (optional)

Method of aggregation of the DataTable table rows having identic geography IDs. Type esriStdGeographyType.

Default: esriStdGeographyTypeFirst.

GeographyIDs (optional)

Array of IDs of the geography level. Type array of string.

TableIDField (optional)

The attribute field name in the input DataTable table which contains geography IDs. Type string.

Other Parameters

Parameter

Description

OutputType (required)

Array of task output options. Options for this endpoint include rendering an output image (GetMapImage), creating a feature layer for subsequent analysis (GetFeatureClass), and creating a report (GetReport). Type array of TaskOutputType.

ActiveDatasetID (optional)

ID of the active dataset. Type string.

Default: ID of the first available dataset.

DataHierarchy (optional)

Name of a hierarchy of data layers used for generating summary reports. Type string. Use the Get Data Hierarchies lookup operation to query available geography hierarchies.

Default: Standard Business Analyst Data.

f (optional)

Response format. Type string. Available formats: HTML, JSON, PJSON, XML.

Default: HTML.

IsFullErrorMessage (optional)

Mode for composing error messages. Type boolean.

Default: false.

OutputAnalysisItem (optional)

Configuration options for storing the output feature layer in the repository. This will enable viewing and working with the output result in subsequent tasks. Type esriFolderItem.

OutputReportItems (optional)

Array of configuration options for storing the output reports in the repository. This will enable viewing and working with the output results in subsequent tasks. Type array of esriFolderItem.

OutputSpatialReference (optional)

An option specifying the spatial reference to return the output feature layer. Type SpatialReference. If this parameter is missing, the output record set will be returned in the default spatial reference. See Get Default Spatial Reference lookup operation to query the default spatial reference.

RenderingParameters (optional)

Configuration options for rendering output when GetMapImage option is specified in the OutputType parameter. Type RenderingParameters.

ReportOptions (optional)

Array specifying summary reports that will be generated using trade/service areas as boundary areas for analysis. Use the Get Report Templates lookup operation to query available report templates. Type array of ReportOptions.

ReturnGeometry (optional)

An option specifying the presence of the shape attribute in the returned record set. Type boolean.

Default: true.

token

Authentication token. This parameter is required if your Business Analyst Server is secured. Type string.

Returns

Variable of type TaskResultOutput

Remarks

The Standard Levels of Geography endpoint allows you to generate trade areas based on predefined geographies. These geographies can be Esri standard demographic layers.

 

The GeographyLevelID parameter specifies the geography level whose geographic units are exported to the output trade area.

 

There are two ways for selection IDs of geographic units from the geography level—using an array of IDs or using a data table.

 

In the first case, the GeographyIDs parameter explicitly specifies the list of IDs of geographic units. In Business Analyst Server 9.3.1 SP1, an ability to join geography features into one combined feature is added. To do this, specify a comma-separated list of feature IDs in an item of the GeographyIDs array by the same manner as in StdLayer. The same feature ID can appear in a number of combined features simultaneously.

 

In the last case, the DataTable parameter specifies a data table and the TableIDField parameter specifies the column of the data table which contains geography IDs required. In Business Analyst Server 9.3.1 SP1, an ability to specify a combined feature is added. To do this, specify a comma-separated list of geography IDs as an ID of feature in the table.

 

The optional AppendFields parameter allows you to export all other columns of the data table to the output trade area layer. Since the data table can contain records with duplicate geography IDs, it is important to specify in this case how the data in rows with a duplicated geographic ID are aggregated. The GeographyFeaturesBehavior parameter specifies the aggregation method—use data from the first matching row (default) or summarize data for all rows having identic geographic IDs.

 

NOTE 1: Since Business Analyst Server 10.0, the SummaryDataLayerID parameter is replaced with an optional DataHierarchy parameter.

 

NOTE 2: Since Business Analyst Server 10.0, the OutputReportItem parameter is replaced with the OutputReportItems parameter which is an array of folder items. The number of items in this array should be equal to the number of items in the ReportOptions array.

How Does it Work

To select standard geography records, a data table with geographic IDs must be generated from which to create the trade areas. This table will be used to select the IDs from the geography layer. Once selected, the features will be exported as a new feature layer.

 

For example, if you want to generate trade areas based on a list of ZIP Codes, you would start by creating a table with all the ZIP Code records you want included in the table. This table may be a territory assignment file created by an external process. The ZIP Code records are then matched to the ZIP Code boundaries provided with the Business Analyst, and a trade area is created with all matching ZIP Codes.

 

All non-matching ZIP Codes will not be included in the output trade area. Non-matching ZIP Codes are ZIP Code records in the table containing matching geography IDs that are not valid and do not have a corresponding feature in the input geography layer.

Usage Tips

• The spatial reference of the output feature layer will be the same as the input geography layer.

• All nonmatching areas of the input geography layer will not be included in the output trade area layer.

Example Usage

The example below creates a trade area based on a standard level of geography. This particular example specifies San Francisco County using its five-digit Federal Information Processing Standard (FIPS) county code.

 

Request

http://localhost:6080/arcgis/rest/services/DefaultMap/MapServer/exts/BAServer/StandardLevelsOfGeography/execute?
GeographyLevelID=US.Counties&GeographyIDs=06075&
OutputType=GetFeatureClass&
f=PJSON

 

Response

{
  "results":
  [
    {
      "paramName":"OutputFeatureClass",
      "dataType":"GPFeatureRecordSetLayer",
      "value":
      {
        "geometryType":"esriGeometryPolygon",
        "spatialReference":
        {
          "wkid":4326
        },
        "fieldAliases":
        {
          "OBJECTID":"Object ID",
          "TA_DESC":"TA_DESC",
          "NAMES":"NAMES",
          "AREA_DESC2":"AREA_DESC2",
          "STORE_ADDR":"STORE_ADDR",
          "ID":"ID"
        },
        "fields":
        [
          {
            "name":"OBJECTID",
            "type":"esriFieldTypeOID",
            "alias":"Object ID"
          },
          ...
          {
            "name":"ID",
            "type":"esriFieldTypeString",
            "alias":"ID",
            "length":255
          }
        ],
        "features":
        [
          {
            "geometry":
            {
              "rings":
              [
                [
                  [
                    -122.492983,
                    37.78783
                  ],
                  ...
                  [
                    -122.492983,
                    37.78783
                  ]
                ],
                ...
                [
                  [
                    -122.384685,
                    37.766681
                  ],
                  ...
                  [
                    -122.384685,
                    37.766681
                  ]
                ]
              ],
              "spatialReference":
              {
                "wkid":4326
              }
            },
            "attributes":
            {
              "OBJECTID":1,
              "TA_DESC":"TA from Geography Level 'US.Counties': 06075",
              "NAMES":"San Francisco County",
              "AREA_DESC2":"Geography:  US.Counties",
              "STORE_ADDR":"06075 (San Francisco County)",
              "ID":"06075"
            }
          }
        ]
      }
    }
  ],
  "messages":
  [
  ]
}

 

NOTE: The response has been abbreviated where "..." is noted.

 

JSON Response Example Rendered with the ArcGIS API for JavaScript

Example Usage Rendering

 

See Also

Business Analyst Server REST Reference