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.

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

Specific Parameters

Other Parameters

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.

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

{
  "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

See Also

• Business Analyst Server REST Reference