Standard Geographies by Attributes Service

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

Query the geographic boundary data layers by string.

Output

The Standard Geographies by Attributes service enables a string-based query on any available data layer. The result of this service is StdGeographiesArrayOfFeatures which contains all of the feature/area names and their corresponding IDs that satisfied the string-based query on the data layer. These feature/area IDs can be used to specify specific geographic areas in subsequent analysis.

Description

The Standard Geographies by Attributes service produces a list of feature/area names and their corresponding IDs based on the result of a string-based query on a data layer. After looking up these IDs, they may be used to specify one or more geographic features/areas in a Summary Reports analysis using StdLayers as the value for the Boundaries parameter. Features/areas in the data layers are often identified by standardized FIPS codes. Alternatively, they may be identified in the data layers by some other ID. Standard Geographies by Attributes can be used to look up these IDs.

Some applications of Standard Geographies by Attribute include the following:

Suppose particular named geographic areas or regions have been identified by stakeholders for analysis. Given the partial or complete names of these areas of interest, Standard Geographies by Attributes can be used to look up their corresponding FIPS codes in order to specify the particular areas of interest in other analyses such as Benchmark Report and Summary Reports.
United States Postal Services (USPS) ZIP code prefixes are a 3-digit code associated with USPS Sectional Center Facilities (SCFs). These SCFs generally represent a particular USPS geographic service area such as a city or part of a city. Standard Geographies by Attributes can be used to look up the ZIP codes containing a 3-digit string. For example, the ZIP code prefix 065 is associated with the USPS SCF for New Haven, Connecticut. In this particular case, every single ZIP code in New Haven is associated with the SCF. By using Standard Geographies by Attributes and specifying the query string 065 on the ZIP code data layer, a complete list of ZIP codes for the city of New Haven will be included in the output response along with all other ZIP codes containing the 065 string. In subsequent analysis, these ZIP code IDs that begin with "065" can be used to specify all New Haven ZIP codes in a Summary Reports analysis service using a StdLayer.

Usage Tips

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 IDs.
While a Web application developer may want to dynamically bind their UI to the Standard Geographies by Attributes endpoint; it may be more efficient, depending on the use case, to pre-save or cache the response in their application if it does not vary.
See Standard Geographies from Extent to query the data layers by a spatial extent.

You can provide arguments to the Standard Geographies by Attribute utility service as defined in the parameters table below.

Parameters

Parameter	Details
GeoLevelID (Required)	Description: A data layer ID to query. Syntax: `GeoLevelID=<string>` Example: `GeoLevelID=US.Tracts` Notes: See Get Standard Geography Levels for a list of available geography data layers.
SearchString (Required)	Description: A string of characters which is used to query the data layer specified by the GeoLevelID parameter value. Syntax: `SearchString=<string>` Example: `SearchString=060` Notes: White space in the attribute values may be substituted with the `+` character (e.g. "san+bernardino+county"). URL encoding also allows the use of `%20` in place of spaces.
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.
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.
f	Description: The response format. Default: HTML Syntax: `f=<HTML \| JSON \| PJSON>` Example: `f=JSON`

Example Usage

Example 1: Obtain a list of all USPS ZIP codes containing "065" and output the response in PJSON format.

Request Example (1)

http://baoapi.esri.com/rest/report/StdGeographiesByAttributes?
f=PJSON&
GeoLevelID=US.ZIP5&
SearchString=065&Token=ABC123

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

Example 2: Look up the feature/area ID of San Bernardino County. (In this case, a FIPS code will be returned.)

Request Example (2)

http://baoapi.esri.com/rest/report/StdGeographiesByAttributes?
f=PJSON&
GeoLevelID=US.Counties&
SearchString=san+bernardino+county&
Token=ABC123

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

White space in the attribute values may be substituted with the + character (e.g. "san+bernardino+county"). URL encoding also allows the use of %20 in place of spaces.

Example Response

JSON Response Syntax

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

Notes: When report templates are specified in other analyses, the values associated with their feature IDs are typically specified.

JSON Response Example (1)

{
  "results": [
    {
      "Feature": [
        {
          "FeatureID": "05065",
          "FeatureName": "Sharon",
          "StateName": "Vermont",
          "StateAbbrev": "VT"
        },
        {
          "FeatureID": "06065",
          "FeatureName": "Riverton",
          "StateName": "Connecticut",
          "StateAbbrev": "CT"
        },
 
        ...
 
        {
          "FeatureID": "98065",
          "FeatureName": "Snoqualmie",
          "StateName": "Washington",
          "StateAbbrev": "WA"
        }
      ]
    }
  ]
}

Notes: When areas are specified in other analyses, the values associated with their feature IDs are typically specified.

The response has been abbreviated in the example where "..." is noted.

JSON Response Example (2)

{
  "results": [
    {
      "Feature": [
        {
          "FeatureID": "06071",
          "FeatureName": "San Bernardino County"
          "StateName": "California",
          "StateAbbrev": "CA"
        }
      ]
    }
  ]
}