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 T D   G E O G R A P H Y   U T I L I T Y

Return Standard Geography Endpoint

Returns IDs and names of features from specified geography levels that match the given location.

 

Availability: Business Analyst Server.

 

URL Example

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

Specific Parameters

Parameter

Description

GeoLevelIDs (required)

Array containing IDs of standard geography levels to find geography features. The list of available geography levels could be retrieved with Get Standard Geography Levels method. Type array of string.

Address (optional)

Location address fields. Type array of string.

Point (optional)

Location coordinates. Type Point.

Points (optional)

Point data layer. Type PointLayer.

ZIP (optional)

Location ZIP code. Type string.

Other Parameters

Parameter

Description

ActiveDatasetID (optional)

ID of the active dataset. Type string.

Default: ID of the first available dataset.

compatibility (optional)

Business Analyst Server version the JSON output is compatible with. Type string.

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.

token

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

Returns

Array of StdGeographiesReturnedFeature containing the list of IDs and names of features of geography levels matching the given location. In the case of JSON and PJSON response types, the response format depends on the compatibility parameter value.

Remarks

The Return Standard Geography endpoint searches in the given standard geography levels for features matching to the given location. Only one feature is selected from matching features per every level of geometry. If no matching feature was found for a level of geometry, the value in corresponding position of the output array is a pair of null or empty ID and Name strings.

 

For example, you can identify standard geography units such as ZIP, Track, Block Group which contain the given point on the map. A point can be specified in a number of ways—using its geographic coordinates, using postal address, or using ZIP Code.

 

The GeoLevelIDs parameter specifies IDs of the standard geography levels to search features.

 

The location point can be specified in one of three ways—by postal address, by geographic coordinates, and by ZIP code:

 

• The Address parameter specifies postal address fields.

• The Point parameter specifies geographic coordinates of the point along with its spatial reference.

• The ZIP parameter specifies the location ZIP Code. The centroid point of the given ZIP code is used.

 

Since Business Analyst Server 10.0, the Points parameter is introduced. It allows you to specify multiple points using a point layer. In this case, features matching to the given locations are combined together and the combined feature ID and Name is returned for a geography level. The ID of a combined feature can be used in the GeographyIDs parameter of the StdLayer type and the Standard Levels of Geography endpoint.

 

NOTE: All the ways for specifying geography locations are mutually exclusive. Only one parameter from Address, Point, ZIP, and Points should be specified and others should be missing.

Example Usage

The example below requests standard geography features matching the given address location.

 

Request

http://localhost:6080/arcgis/rest/services/DefaultMap/MapServer/exts/BAServer/ReturnStdGeography/execute?
GeoLevelIDs=US.WholeUSA;US.States;US.Counties;US.Tracts;US.ZIP5;US.BlockGroups;US.CBSA;US.DMA;US.Places;US.CD;US.CS&
Address=380+New+York+St.;Redlands;CA&
f=PJSON

 

Response

{
  "results":
  [
    {
      "paramName":"StdGeographyFeatures",
      "dataType":"BAStdGeographiesFeatures",
      "value":
      [
        {
          "ID":"01",
          "Name":"United States"
        },
        {
          "ID":"06",
          "Name":"California"
        },
        {
          "ID":"06071",
          "Name":"San Bernardino County"
        },
        {
          "ID":"06071008100",
          "Name":"060710081.00"
        },
        {
          "ID":"92373",
          "Name":"Redlands"
        },
        {
          "ID":"060710081002",
          "Name":"060710081.002"
        },
        {
          "ID":"40140",
          "Name":"Riverside-San Bernardino-Ontario, CA Metropolitan Statistical Area"
        },
        {
          "ID":"803",
          "Name":"Los Angeles, CA"
        },
        {
          "ID":"0659962",
          "Name":"Redlands city"
        },
        {
          "ID":"0641",
          "Name":"California - District 41"
        },
        {
          "ID":"0607192770",
          "Name":"San Bernardino CCD"
        }
      ]
    }
  ],
  "messages":
  [
  ]
}

 

The example below requests standard geography features matching the given point coordinates.

 

Request

http://localhost:6080/arcgis/rest/services/DefaultMap/MapServer/exts/BAServer/ReturnStdGeography/execute?
GeoLevelIDs=US.WholeUSA;US.States;US.Counties;US.Tracts;US.ZIP5;US.BlockGroups;US.CBSA;US.DMA;US.Places;US.CD;US.CS&
Point={"x":-77.24642,"y":38.92903}&
f=PJSON

 

Response

{
  "results":
  [
    {
      "paramName":"StdGeographyFeatures",
      "dataType":"BAStdGeographiesFeatures",
      "value":
      [
        {
          "ID":"01",
          "Name":"United States"
        },
        {
          "ID":"51",
          "Name":"Virginia"
        },
        {
          "ID":"51059",
          "Name":"Fairfax County"
        },
        {
          "ID":"51059460400",
          "Name":"510594604.00"
        },
        {
          "ID":"22182",
          "Name":"Vienna"
        },
        {
          "ID":"510594604002",
          "Name":"510594604.002"
        },
        {
          "ID":"47900",
          "Name":"Washington-Arlington-Alexandria, DC-VA-MD-WV Metropolitan Statistical Area"
        },
        {
          "ID":"511",
          "Name":"Washington, DC (Hagerstown, MD)"
        },
        {
          "ID":"5179952",
          "Name":"Tysons Corner CDP"
        },
        {
          "ID":"5108",
          "Name":"Virginia - District 8"
        },
        {
          "ID":"5105993943",
          "Name":"Hunter Mill district"
        }
      ]
    }
  ],
  "messages":
  [
  ]
}

 

The example below requests standard geography features matching the given point layer.

 

NOTE: Feature attributes are required in a Record Set and must contain at least one attribute.

 

Request

http://localhost:6080/arcgis/rest/services/DefaultMap/MapServer/exts/BAServer/ReturnStdGeography/execute?
GeoLevelIDs=US.WholeUSA;US.States;US.Counties;US.Tracts;US.ZIP5;US.BlockGroups;US.CBSA;US.DMA;US.Places;US.CD;US.CS&
Points={
  "RecordSet":{
    "geometryType":"esriGeometryPoint",
    "spatialReference":{"wkid":4326},
    "features":[
      {
        "geometry":{
          "x":-117.194152, 
          "y":34.057165, 
          "spatialReference":{"wkid":4326}
        },
        "attributes":{
          "STORE_ID" : "1",
          "NAME" : "store1",
          "DESCR" : "Redlands Office"
        } 
      },
      {
        "geometry":{
          "x":-117.232605, 
          "y":32.870896, 
          "spatialReference":{"wkid":4326}
        },
        "attributes":{
          "STORE_ID" : "2",
          "NAME" : "store2",
          "DESCR" : "La Jolla Office"
        }
      }
    ]
  }
}&
f=PJSON

 

Response

{
  "results":
  [
    {
      "paramName":"StdGeographyFeatures",
      "dataType":"BAStdGeographiesFeatures",
      "value":
      [
        {
          "ID":"01",
          "Name":"United States"
        },
        {
          "ID":"06",
          "Name":"California"
        },
        {
          "ID":"06071,06073",
          "Name":"San Bernardino County;San Diego County"
        },
        {
          "ID":"06073008315,06071008100",
          "Name":"060730083.15;060710081.00"
        },
        {
          "ID":"92373,92037",
          "Name":"Redlands;La Jolla"
        },
        {
          "ID":"060730083151,060710081002",
          "Name":"060730083.151;060710081.002"
        },
        {
          "ID":"40140,41740",
          "Name":"Riverside-San Bernardino-Ontario, CA Metropolitan Statistical Area;San Diego-Carlsbad-San Marcos, CA Metropolitan Statistical Area"
        },
        {
          "ID":"825,803",
          "Name":"San Diego, CA;Los Angeles, CA"
        },
        {
          "ID":"0659962,0666000",
          "Name":"Redlands city;San Diego city"
        },
        {
          "ID":"0641,0653",
          "Name":"California - District 41;California - District 53"
        },
        {
          "ID":"0607192770,0607392780",
          "Name":"San Bernardino CCD;San Diego CCD"
        }
      ]
    }
  ],
  "messages":
  [
  ]
}

 

See Also

Business Analyst Server REST Reference