Return Standard Geography Service

URL	`http://baoapi.esri.com/rest/report/ReturnStdGeography`

Get a list of standard geographic area names and IDs which intersect a given point location.

Output

The Return Standard Geography utility service queries standard geography levels for standard geographic features intersecting the given point location. The result of this service is a StdGeographiesArrayOfFeatures object which contains the list of intersecting standard geography features, including their feature IDs. These feature IDs can be used to specify standard geography areas in subsequent operations in an analysis workflow.

Description

The Return Standard Geography service returns a list of intersecting standard geography features for a given point location for one or more standard geography levels using a latitude-longitude coordinate pair, a street address, or the centroid (geographic center) of a ZIP code.

Some applications of Return Standard Geography include the following:

A web application developer may want to consume the output of the Return Standard Geography service in order to populate a dynamically-bound data grid control after selecting a location.
Stakeholders for a business, organization, or agency may want to look up the FIPS or other ID codes for standard geographic features such as counties, ZIP codes, Census tracts, and U.S. Congressional Districts which intersect or touch a location of interest. These IDs can then be used to specify these areas in subsequent analysis services such as Benchmark Report and Summary Reports.

Usage Tips

While it is possible to specify the point input location three different ways (latitude-longitude coordinate pair, street address, or center/centroid of a ZIP code), only one method can be used in each Web request since the option to specify location is mutually exclusive.
The feature IDs of standard geography features can be used in the TradeAreas parameter value in the Benchmark Report service and in the Boundaries parameter in the Summary Reports service when specifying standard geographic areas such as ZIP codes, U.S. Census tracts, U.S. counties, U.S. Congressional Districts, etc. Additionally, the Summary Reports service can be leveraged to retrieve the polygon FeatureSet representations of standard geography areas so they can be mapped or represented in client applications.
Only one intersecting standard geography feature will be returned for each specified standard geography data layer when there is an intersection.
If no matching standard geography features are returned in the query, the output StdGeographiesArrayOfFeatures will contain StdGeographiesReturnedFeature with empty FeatureID and FeatureName properties for the respective data layers.
Take advantage of all of the available analysis data layers in REST services. Use Get Standard Geography Levels to look up the available data layers and their corresponding data layer IDs.
See Standard Geographies from Extent to query the data layers by spatial extent.
See Standard Geographies by Attributes to query the data layers by standard geography feature name or ID.

You can provide arguments to the Return Standard Geography utility service as defined in the parameters table below.

Parameters

Parameter	Details
GeoLevelIDs (Required)	Description: A data layer ID to query. Syntax: `GeoLevelIDs=<string>` Example: `GeoLevelIDs=US.Tracts` Notes: See Get Standard Geography Levels for a list of available geography data.
Token (Required)	Description: A valid REST services token string. Syntax: `Token=<string>` Example: `Token=ABC123...` Notes: The value associated with the Token parameter is for example purposes only. See Get Token for more information on obtaining a token.
ActiveDatasetID	Description: Specify a dataset to perform Online API tasks or operations. Default: USA Syntax: `ActiveDatasetID=<string>` Example: `ActiveDatasetID=Canada` Notes: See the Get Datasets task to dynamically query the available dataset IDs. Access to additional datasets is subject to the type, terms and restrictions associated with your Online API subscription.
Address	Description: The street address of the point as address;city;state;ZIP Default: null Syntax: `Address=<ArrayOfString>` Example: `Address=380 New York St.;Redlands;CA;92373` Notes: Known Dependencies: Only one street address is supported for each analysis request. The Address, Coordinates, and ZIP parameters are mutually exclusive. Only one of these may be used to specify the point location in each analysis request.
Callback	Description: Wrap the JSON or PJSON response in a named function that can be executed by client-side JavaScript upon receipt. Default: `null` Syntax: `Callback=<string>` Example: `Callback=MyCallbackFunction` Notes: The response will be wrapped in a callback function only if a non-null Callback parameter value is specified and if the response format (the `f` parameter) is set to JSON or PJSON. Callback functions are useful for consuming the service in JavaScript-based client applications as shown in this basic example.
Coordinates	Description: The geographical coordinates of the point as X;Y Syntax: `Coordinates=<ArrayOfDouble>` Example: `Coordinates=-117.195;34.057` Notes: Known Dependencies: Only one coordinate pair is supported for each analysis request. The Address, Coordinates, and ZIP parameters are mutually exclusive. Only one of these may be used to specify the point location in each analysis request. Coordinates are specified in the geographic coordinate system and are specified as longitude;latitude separated by a semicolon with no white space between the elements. The default coordinate system is GCS_WGS_1984 (WKID: 4326).
f	Description: The response format. Default: HTML Syntax: `f=<HTML \| JSON \| PJSON>` Example: `f=JSON`
ZIP	Description: The ZIP code of the input point (The center/centroid of the ZIP code will be used). Default: null Syntax: `ZIP=<string>` Example: `ZIP=92373` Notes: Known Dependencies: Only one ZIP coce is supported for each analysis request. The Address, Coordinates, and ZIP parameters are mutually exclusive. Only one of these may be used to specify the point location in each analysis request.

Example Usage

Example 1: Lookup the standard geography features in several data layers which intersect the given coordinates (point).

Request Example (1)

http://baoapi.esri.com/rest/report/ReturnStdGeography?
f=PJSON&
GeoLevelIDs=US.WholeUSA;US.States;US.Counties;US.Tracts;US.ZIP5;US.BlockGroups;US.CBSA;US.DMA;US.Places;US.CD;US.CS&
Coordinates=-117.195;34.057&
Token=ABC123

Notes: See Get Token for more information on obtaining a token.

Example 2: Lookup the standard geography features in several data layers which intersect the given address (point).

Request Example (2)

http://baoapi.esri.com/rest/report/ReturnStdGeography?
f=PJSON&
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;92373&
Token=ABC123

Notes: See Get Token for more information on obtaining a token.

White space in the property values may be substituted with the + character (e.g. "101+Some+Street"). URL encoding also allows the use of %20 in place of spaces.

Example 3: Lookup the standard geography features in several data layers which intersect the given ZIP code centroid (point).

Request Example (3)

http://baoapi.esri.com/rest/report/ReturnStdGeography?
f=PJSON&
GeoLevelIDs=US.WholeUSA;US.States;US.Counties;US.Tracts;US.ZIP5;US.BlockGroups;US.CBSA;US.DMA;US.Places;US.CD;US.CS&
ZIP=92373&
Token=ABC123

Notes: See Get Token for more information on obtaining a token.

Example Response

JSON Response Syntax

{
  "results": [
    {
      "Feature": <StdGeographiesArrayOfFeatures>
    }
  ]
}

JSON Response Example (1) and (2)

{
  "results": [
    {
      "Feature": [
        {
          "FeatureID": "01",
          "FeatureName": "United States"
        },
        {
          "FeatureID": "06",
          "FeatureName": "California"
        },
        {
          "FeatureID": "06071",
          "FeatureName": "San Bernardino County"
        },
        {
          "FeatureID": "06071008100",
          "FeatureName": "060710081.00"
        },
        {
          "FeatureID": "92373",
          "FeatureName": "Redlands"
        },
        {
          "FeatureID": "060710081002",
          "FeatureName": "060710081.002"
        },
        {
          "FeatureID": "40140",
          "FeatureName": "Riverside-San Bernardino-Ontario, CA Metropolitan Statistical Area"
        },
        {
          "FeatureID": "803",
          "FeatureName": "Los Angeles, CA"
        },
        {
          "FeatureID": "0659962",
          "FeatureName": "Redlands city"
        },
        {
          "FeatureID": "0641",
          "FeatureName": "California - District 41"
        },
        {
          "FeatureID": "0607192770",
          "FeatureName": "San Bernardino CCD"
        }
      ]
    }
  ]
}

JSON Response Example (3)

{
  "results": [
    {
      "Feature": [
        {
          "FeatureID": "01",
          "FeatureName": "United States"
        },
        {
          "FeatureID": "06",
          "FeatureName": "California"
        },
        {
          "FeatureID": "06071",
          "FeatureName": "San Bernardino County"
        },
        {
          "FeatureID": "06071008500",
          "FeatureName": "060710085.00"
        },
        {
          "FeatureID": "92373",
          "FeatureName": "Redlands"
        },
        {
          "FeatureID": "060710085004",
          "FeatureName": "060710085.004"
        },
        {
          "FeatureID": "40140",
          "FeatureName": "Riverside-San Bernardino-Ontario, CA Metropolitan Statistical Area"
        },
        {
          "FeatureID": "803",
          "FeatureName": "Los Angeles, CA"
        },
        {
          "FeatureID": "0659962",
          "FeatureName": "Redlands city"
        },
        {
          "FeatureID": "0641",
          "FeatureName": "California - District 41"
        },
        {
          "FeatureID": "0607192770",
          "FeatureName": "San Bernardino CCD"
        }
      ]
    }
  ]
}

Output

Description

Usage Tips

Parameters

Example Usage

Example Response

See Also