| URL | http://baoapi.esri.com/rest/report/StdGeographiesFromExtent |
|---|
Query the geographic boundary data layers by spatial extent.
Output
The Standard Geographies from Extent service enables a spatial 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 spatial query on the data layer. These feature/area IDs can be used to specify specific geographic areas in subsequent analysis.
Description
The Standard Geographies from Extent service produces a list of feature/area names and their corresponding IDs based on the result of a spatial 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 from Extent include the following:
- Geographic areas of an arbitrary size or shape can be used to perform a spatial query of Business Analyst's data layers to look up the FIPS and other ID codes of the areas of interest. Subsequently, these codes and IDs can be used to specify these areas in other analysis services such as Benchmark Report and Summary Reports.
- The Standard geographies from Extent service can be leveraged for a quick lookup of FIPS codes and other IDs of named areas in a specific trade/service area. These named areas can be areas identified by ZIP codes, Census Tracts, County Subdivisions, Congressional Districts, etc. See Get Standard Geography Levels for the list of all geographic data layers.
Usage Tips
- The output Polygon feature class Geometry from other analysis services such as Drive Time and Simple Rings can be used as extent Polygons in the AnalysisExtent parameter. Additionally, Polygons drawn with mapping client applications can be submitted as well.
- 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 from Extent 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 by Attributes to query the data layers by name or ID.
You can provide arguments to the Standard Geographies from Extent utility service as defined in the parameters table below.
Parameters
| Parameter | Details |
|---|---|
| GeoLevelID (Required) |
Description:
The data layer ID to query.
Syntax: Notes: See Get Standard Geography Levels for a list of available geography data layers. |
| AnalysisExtent (Required) |
Description:
The spatial/geographic extent on which to perform the query. This parameter expects a value of type ExtentData. ExtentData can consist of either ExtentCoordinates or a 2-D Geometry of at least three points specifying an area.
Default: null
Syntax:
Syntax (1) (ExtentData as ExtentCoordinates): {
"Coordinates": <ExtentCoordinates>
}
Example (1) (ExtentData as ExtentCoordinates): {
"Coordinates": {
"XMin": -84.020313,
"XMax": -82.457595,
"YMin": 41.983507,
"YMax": 41.983507,
"CoordinateSystem": 4326
}
}
Notes: For a list of valid coordinate system values, see Projected coordinate Systems and Geographic coordinate Systems. ExtentCoordinates define a rectangular extent "envelope" and must fall within the area covered by the data layers. Syntax (2) (ExtentData as Polygon): {
"Extent": <Polygon>
}
Example (2) (ExtentData as Polygon): {
"Extent": {
"rings": [
[
[-82.457595,41.983507],
[-82.457595,42.885916],
[-83.733139,43.240413],
[-84.949773,42.940422],
[-84.943043,42.554298],
[-84.020313,41.983507],
[-82.457595,41.983507]
]
],
"spatialReference": {"wkid" : 4326}
}
}
Notes: If a Polygon type of Geometry is used to define ExtentData, it should only consist of a single ring. A polygon ring's last coordinate pair should be "connected" to the first coordinate pair to "close" off the polygon shape. Also, per convention, coordinate pairs for the polygon vertices should be listed in counter-clockwise "draw order" to define an area inside the perimeter formed by the vertices. For a list of valid WKID values, see Projected coordinate Systems and Geographic coordinate Systems. The area defined by the 2-D Geometry must fall within the area covered by the data layers. Syntax (3) (ExtentData as Envelope): {
"Extent": <Envelope>
}
Syntax (3) (ExtentData as Envelope): {
"Extent": {
"xmin": -84.020313,
"ymin": 41.983507,
"xmax": -82.457595,
"ymax": 42.885916,
"SpatialReference": {"wkid": 4326}
}
}
Notes: For a list of valid WKID values, see Projected coordinate Systems and Geographic coordinate Systems. The area defined by the 2-D Geometry must fall within the area covered by the Services analysis data set. |
| SpatialRelationship (Required) |
Description:
The spatial selection method used with the AnalysisExtent to define the area of analysis. This parameter expects an enumeration value of type esriSpatialRelEnum.
Default: null
Syntax:
Notes: For more detailed information regarding the spatial relationship options, see this link. |
| Token (Required) |
Description:
A valid REST services token string.
Syntax: 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 Notes: See the Get Datasets task to dynamically query the available dataset IDs. |
| Callback |
Description: Wrap the JSON or PJSON response in a named function that can be executed by client-side JavaScript upon receipt.
Default: Notes:
|
| f |
Description:
The response format.
Default: HTML
Syntax: |
Example Usage
Example 1: Obtain a list of all U.S. Census tracts which intersect an extent Envelope.
Example (1) Input Extent Envelope Rendered with the ArcGIS API for JavaScript
Request Example (1)
Notes: See Get Token for more information on obtaining a token.
Example 2: Obtain a list of all ZIP codes intersecting a custom Polygon.
Example (2) Input Extent Polygon Rendered with the ArcGIS API for JavaScript
Request Example (2)
Notes: See Get Token for more information on obtaining a token.
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": "06071008402",
"FeatureName": "060710084.02"
},
{
"FeatureID": "06071008403",
"FeatureName": "060710084.03"
},
{
"FeatureID": "06071008404",
"FeatureName": "060710084.04"
}
]
}
]
}
Notes: When areas are specified in other analyses, the values associated with their feature IDs are typically specified.
JSON Response Example (2)
{
"results": [
{
"Feature": [
{
"FeatureID": "92373",
"FeatureName": "Redlands"
},
{
"FeatureID": "92374",
"FeatureName": "Redlands"
}
]
}
]
}
Notes: When areas are specified in other analyses, the values associated with their feature IDs are typically specified.