FRAMES | NO FRAMES

 

B U S I N E S S   A N A L Y S T   10.2   R E S T   S E G M E N T A T I O N   T A S K

Game Plan Map Endpoint

Divides sites in the area of interest into one of four categories and thematically shades each site based on the output from the Game Plan Chart.

 

Availability: Business Analyst Server.

 

URL Example

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

Specific Parameters

Parameter

Description

AnalysisExtent (required)

Analysis extent. Type ExtentData.

DefineSegmentsExplicitly (required)

Way for defining segments. Type boolean.

SegmentationBase (required)

Segmentation base. Use the GetSegBases lookup operation to query available segmentation bases. Type string.

SegmentationLevel (required)

Segmentation level ID. Use the GetSegmentationLevels lookup operation to query available segmentation level IDs and names. Type string.

BaseProfile (optional)

Base segmentation profile. Type ProfileData.

CoreSegments (optional)

Array of Core segment IDs. Type array of string.

DevelopmentalSegments (optional)

Array of Developmental segment IDs. Type array of string.

IndexThreshold (optional)

Index threshold. Type double.

NicheSegments (optional)

Array of Niche segment IDs. Type array of string.

PercentThreshold (optional)

Percent composition threshold. Type double.

TargetProfile (optional)

Target segmentation profile. Type ProfileData.

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.

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.

OutputReportItem (optional)

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

OutputSpatialReference (optional)

An option specifying the spatial reference to return the output feature layer in. 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. Available with Business Analyst Server 10.0 SP1.

RenderingParameters (optional)

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

ReturnGeometry (optional)

An option specifying the presence of the shape attribute in the returned record set. Type boolean. Available with Business Analyst Server 10.0 SP1.

Default: true.

StandardReportOptions (optional)

Report parameters. Type ReportOptions. The TemplateName parameter is ignored.

token

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

Returns

Variable of type TaskResultOutput

Remarks

The GamePlanMap method creates a thematically shaded map from a geography level and from the result of a Game Plan Chart in which a target profile is compared to a base profile.

 

The AnalysisExtent parameter specifies the market area to thematically shade locations. The SegmentationBase parameter specifies the base for assignment segments to geography sites. The SegmentationLevel parameter specifies the ID of a segmentation level.

 

There are two ways to divide the Tapestry segments into categories—explicit specification of Core, Developmental, Niche, and Other segments, and categorizing segments on the base of a Game Plan Chart.

 

In the case of explicit specification, the DefineSegmentsExplicitly parameter should have the true value and the optional CoreSegments, DevelopmentalSegments, and NicheSegments parameters can specify the categorization of segments by explicit enumerating the IDs of segments belonging to their categories. If a Tapestry segment is missing in all these categories, it is considered to belong to the category of other segments. At least one category should be a nonempty array.

 

In the case of using the Game Plan Chart, the DefineSegmentsExplicitly parameter should have the false value and two tapestry segmentation profiles should be specified—the base profile (BaseProfile parameter) is used for calculating the index and the target profile (TargetProfile parameter) is used for calculating the percent composition for each Tapestry segment. The IndexThreshold and PercentThreshold parameters should specify positions of Index and Percent Composition axes on the Game Plan Chart. In most cases, the Index axis should be set to a value of at least 100. The Percent Composition axis should be set so you have at least three segments in the Core category. Often there will be a natural break in the percent composition values.

How Does it Work

The sample graph below illustrates how the GamePlanMap endpoint works. It assigns a color to every site of a geography level based on its segmentation assignment and its segment to a quadrant of the Game Plan Chart. In the example below, a section of block groups in San Francisco, California, have been mapped in conjunction with the graph above. All the sites that fall into the Core quadrant are within the dark blue section of the graph.

 

Usage Tips

• To best determine what your Index and Percent Composition axes values should be, you should analyze the output from the Customer Tapestry Profile Report.

• In most cases, the Index axis should be set to a value of at least 100.

• The Percent Composition axis should be set so you have at least three segments in the Core category. Often there will be a natural break in the percent composition values.

• The base segmentation profile can be generated using the Profile by Area Summation endpoint.

• Usually the target segmentation profile is based on customer records.

• The target segmentation profile can be generated using the Profile by Table Geocoding endpoint.

• Customers in the target profile should be wholly contained within the base profile.

• If you are unclear what to use as the base profile, you can use the whole United States.

• The segmentation base can be generated using total adult population or total households.

• Total adult population includes individuals 18 years or older.

Example Usage

The example below illustrates a workflow to create a Game Plan Map and a report. This workflow includes the preliminary steps of creating of a target customer profile from a table of customers and their cumulative purchase amounts and creation of a base profile for the sales territory.

 

NOTE: The example uses the "Drive Time Polygons 1" polygon layer already created in the Trade Areas folder of the San Francisco Tutorial Project of the Default Workspace.

 

STEP 1: Create a base profile

http://localhost:6080/arcgis/rest/services/DefaultMap/MapServer/exts/BAServer/ProfileByAreaSummation/execute?
Boundaries={"Item":{
  "WorkspaceName":"Default Workspace",
  "ProjectName":"San Francisco Tutorial Project",
  "folderType":"esriFolderTradeAreas",
  "itemName":"Drive Time Polygons 1"
}}&
SegmentationBase=Total Households&AreaIDField=RING&
OutputItem={
  "WorkspaceName":"Default Workspace",
  "ProjectName":"Default Project",
  "folderType":"esriFolderSegProfiles",
  "itemName":"sampleBaseSegProfile_GamePlanMap"
}&
f=PJSON

 

STEP 2: Create a target profile

http://localhost:6080/arcgis/rest/services/DefaultMap/MapServer/exts/BAServer/ProfileByImportFromTable/execute?
DataTable={"RecordSet":{"features":[
  {"geometry":{},"attributes":{"OID":1,"CUST_TYPE":"Target1","SEG_CODE":"1","COUNT":12320}},
  {"geometry":{},"attributes":{"OID":2,"CUST_TYPE":"Target2","SEG_CODE":"3","COUNT":3415}},
  {"geometry":{},"attributes":{"OID":3,"CUST_TYPE":"Target3","SEG_CODE":"9","COUNT":13415}}
]}}&
IDField=SEG_CODE&
CountField=COUNT&OutputItem={
  "WorkspaceName":"Default Workspace",
  "ProjectName":"Default Project",
  "folderType":"esriFolderSegProfiles",
  "itemName":"sampleTargetSegProfile_GamePlanMap"
}&
f=PJSON

 

STEP 3: Execute the GamePlanMap request

http://localhost:6080/arcgis/rest/services/DefaultMap/MapServer/exts/BAServer/GamePlanMap/execute?
SegmentationLevel=US.BlockGroups&
SegmentationBase=Total Households&
AnalysisExtent={"Extent":{
  "spatialReference":{"wkid":4326},
  "xmin":-122.565,
  "xmax":-122.346,
  "ymin":37.99,
  "ymax":37.8634
}}&
DefineSegmentsExplicitly=false&BaseProfile={"Item":{
  "WorkspaceName":"Default Workspace",
  "ProjectName":"Default Project",
  "folderType":"esriFolderSegProfiles",
  "itemName":"sampleBaseSegProfile_GamePlanMap"
}}&
TargetProfile={"Item":{
  "WorkspaceName":"Default Workspace",
  "ProjectName":"Default Project",
  "folderType":"esriFolderSegProfiles",
  "itemName":"sampleTargetSegProfile_GamePlanMap"
}}&
PercentThreshold=10&
IndexThreshold=200&
StandardReportOptions={
  "ReportFormat":"PDF",
  "ReportHeader":[{"key":"subtitle","value":"Custom Report Title"}]
}&
OutputType=GetFeatureClass;GetReport&
f=PJSON

 

Response

{
 "results": [
  {
   "paramName": "RecordSet",
   "dataType": "GPFeatureRecordSetLayer",
   "value": {
    "displayFieldName": "",
    "fieldAliases": {
     "OBJECTID": "Object ID",
     "NAME": "NAME",
     "ID": "ID",
     "HH01": "2011 HHs in Tapestry Seg 1",
     "HH02": "2011 HHs in Tapestry Seg 2",
     "HH03": "2011 HHs in Tapestry Seg 3",
     ...
     "HH66": "2011 HHs in Tapestry Seg 66",
     "Value": "Value"
    },
    "geometryType": "esriGeometryPolygon",
    "spatialReference": {
     "wkid": 4326,
     "latestWkid": 4326
    },
    "fields": [
     {
      "name": "OBJECTID",
      "type": "esriFieldTypeOID",
      "alias": "Object ID"
     },
     {
      "name": "NAME",
      "type": "esriFieldTypeString",
      "alias": "NAME",
      "length": 35
     },
     {
      "name": "ID",
      "type": "esriFieldTypeString",
      "alias": "ID",
      "length": 5
     },
     {
      "name": "HH01",
      "type": "esriFieldTypeInteger",
      "alias": "2011 HHs in Tapestry Seg 1"
     },
     {
      "name": "HH02",
      "type": "esriFieldTypeInteger",
      "alias": "2011 HHs in Tapestry Seg 2"
     },
     {
      "name": "HH03",
      "type": "esriFieldTypeInteger",
      "alias": "2011 HHs in Tapestry Seg 3"
     },
     ...
     {
      "name": "HH66",
      "type": "esriFieldTypeInteger",
      "alias": "2011 HHs in Tapestry Seg 66"
     },
     {
      "name": "Value",
      "type": "esriFieldTypeString",
      "alias": "Value",
      "length": 13
     }
    ],
    "features": [
     {
      "attributes": {
       "OBJECTID": 1,
       "NAME": "ALAMEDA",
       "ID": "94501",
       "HH01": 0,
       "HH02": 0,
       "HH03": 322,
       ...
       "HH66": 0,
       "Value": "Other"
      },
      "geometry": {
       "rings": [
        [
         [
          -122.2653100334017,
          37.7863399517407
         ],
         [
          -122.2614701847197,
          37.784699973136696
         ],
         [
          -122.2572198059529,
          37.7819499100234
         ],
         ...
         [
          -122.26697012004681,
          37.785989950703595
         ],
         [
          -122.2653100334017,
          37.7863399517407
         ]
        ]
       ]
      }
     },
     {
      "attributes": {
       "OBJECTID": 2,
       "NAME": "BELVEDERE TIBURON",
       "ID": "94920",
       "HH01": 2417,
       "HH02": 0,
       "HH03": 1717,
       ...
       "HH66": 14,
       "Value": "Other"
      },
      "geometry": {
       "rings": [
        [
         [
          -122.4273701530756,
          37.870650006959394
         ],
         [
          -122.42688012208811,
          37.870390110768795
         ],
         [
          -122.42598989164159,
          37.870419894280502
         ],
         ...
         [
          -122.48589000394429,
          37.920969967536095
         ],
         [
          -122.4857301038237,
          37.920910087069799
         ]
        ]
       ]
      }
     },
     {
      "attributes": {
       "OBJECTID": 3,
       "NAME": "BRISBANE",
       "ID": "94005",
       "HH01": 0,
       "HH02": 0,
       "HH03": 0,
       ...
       "HH66": 0,
       "Value": "Other"
      },
      "geometry": {
       "rings": [
        [
         [
          -122.3933599364189,
          37.708240171032401
         ],
         [
          -122.3935598115696,
          37.708089860118406
         ],
         [
          -122.3936900672858,
          37.707879850742302
         ],
         ...
         [
          -122.3934502171049,
          37.708240171032401
         ],
         [
          -122.3933599364189,
          37.708240171032401
         ]
        ]
       ]
      }
     },
     ...
     {
      "attributes": {
       "OBJECTID": 37,
       "NAME": "UCSF",
       "ID": "94143",
       "HH01": 0,
       "HH02": 0,
       "HH03": 0,
       ...
       "HH66": 0,
       "Value": "Other"
      },
      "geometry": {
       "rings": [
        [
         [
          -122.45523005413969,
          37.759050162795404
         ],
         [
          -122.4553998357284,
          37.758620134446005
         ],
         [
          -122.4554299292904,
          37.758609836461503
         ],
         ...
         [
          -122.45568011009701,
          37.759060105617806
         ],
         [
          -122.45523005413969,
          37.759050162795404
         ]
        ]
       ]
      }
     }
    ]
   }
  },
  {
   "paramName": "GamePlanMapReport.PDF",
   "dataType": "GPDataFile",
   "value": {
    "url": "http://localhost:6080/arcgis/rest/directories/arcgisoutput/DefaultMap_MapServer/_ags_T322C40DF94A3881EB67FC351B5098.pdf"
   }
  }
 ],
 "messages": [
  
 ]
}

 

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

 

See Also

Game Plan Chart Endpoint

Tapestry Profile Report Endpoint

Target Map Endpoint

Target Penetration Map Endpoint

Business Analyst Server REST Reference