Query the Business Analyst Online geographic boundary data layers by spatial extent.
StdGeographiesReturnedFeature[] StdGeographiesFromExtent (
StdGeographiesFromExtentParams Parameters
);
| Parameter | Description |
|---|---|
| Parameters | Geographic search parameters. Type StdGeographiesFromExtentParams. |
Returns
Variable of type StdGeographiesReturnedFeature[].
The Standard Geographies from Extent service enables a spatial query on any available Business Analyst Online standard geography/administrative boundary data layer. The result of this service is an array of StdGeographiesReturnedFeatures 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.
Remarks
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 Business Analyst Online 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 Business Analyst Online data layers are often identified by standardized FIPS codes. Alternatively, they may be identified in the Business Analyst Online 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 Online'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 Business Analyst Online 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 standard geography/administrative boundary data layers in the Business Analyst Online API 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 Business Analyst Online data layers by name or ID.
- View and execute the code examples which leverage the BAOReportHelper class: Example 1
- View and execute the code examples which consume the BAOReport proxy class without leveraging the BAOReportHelper class: Example 2, Example 3
Examples
Example 1: Retrieve the names and IDs of standard geography features in a given Business Analyst standard geography data layer based on an input spatial extent envelope and generate summary reports describing the returned areas.Notes: Example 1 demonstrates the use of the BAOReportHelper class. For information about code that consumes the BAOReport proxy class, (generated from the WSDL ) without leveraging the BAOReportHelper class, please refer to the BAOReport vs BAOReportHelper comparison chart and see the additional Examples below.
Output Report Created with Example
Example (1) Code
| C# |
// Authentication: Uses BAOReportHelper class for token management.
// Instantiate BAOReportHelper class
string tokenServiceUrl = "https://baoapi.esri.com/bawebservices/rest/authentication";
// Business Analyst Online API Sample credentials.
// NOTE: These credentials are associated with an
// account which constrains analysis to the
// two ZIP codes in Redlands, CA.
string username = "BAOAPISAMPLE"; // Substitute user name here
string password = "baoapisample"; // Substitute password here
ITokenProvider tokenProvider = new HTTPTokenProvider(tokenServiceUrl, username, password);
BAOReportHelper baoReportHelper = new BAOReportHelper(tokenProvider);
// Define an input extent Envelope
ExtentCoordinates coordinates = new ExtentCoordinates();
coordinates.XMin = -117.171502;
coordinates.XMax = -117.154933;
coordinates.YMin = 34.052656;
coordinates.YMax = 34.060632;
coordinates.CoordinateSystem = 4326; // WGS_1984 coordinate system.
// Specify extent data
ExtentData extent = new ExtentData();
extent.Coordinates = coordinates;
// Specify parameters of StdGeographiesFromExtent task
StdGeographiesFromExtentParams parameters = new StdGeographiesFromExtentParams();
parameters.GeoLevelID = "US.Tracts";
parameters.SpatialRelationship = esriSpatialRelEnum.esriSpatialRelOverlaps;
parameters.AnalysisExtent = extent;
// Get a list of all ZIP codes in the study area
StdGeographiesReturnedFeature[] locations = baoReportHelper.StdGeographiesFromExtent(parameters);
// Create data layer based on the returned Census Tracts
StdLayer stdLayer = new StdLayer();
stdLayer.ID = "US.Tracts";
stdLayer.GeographyIDs = new string[locations.Length];
for (int i = 0; i < locations.Length; i++)
{
stdLayer.GeographyIDs[i] = locations[i].FeatureID;
}
DataLayer dataLayer = new DataLayer();
dataLayer.StdLayer = stdLayer;
// Specify report options
ReportOptions ro1 = new ReportOptions();
ro1.ReportFormat = "PDF";
ro1.ReportHeader = null;
ro1.TemplateName = "dandi";
// Specify parameters of SummaryReports task
SummaryReportsParameters reportsParameters = new SummaryReportsParameters();
reportsParameters.ReportOptions = new ReportOptions[] { ro1 };
reportsParameters.AreaIDField = "ID";
reportsParameters.Boundaries = dataLayer;
// Execute the task
TaskResultOutput result = baoReportHelper.SummaryReports(reportsParameters);
// The result is a Demographic and Income Report of the aggregated area
// consisting of all of the U.S. Census Tracts in the input extent.
|
Example (1) Code
| VB.NET |
' Authentication: Uses BAOReportHelper class for token management.
' Instantiate BAOReportHelper class
Dim tokenServiceUrl As String = "https://baoapi.esri.com/bawebservices/rest/authentication"
' Business Analyst Online API Sample credentials.
' NOTE: These credentials are associated with an
' account which constrains analysis to the
' two ZIP codes in Redlands, CA.
Dim username As String = "BAOAPISAMPLE"
' Substitute user name here
Dim password As String = "baoapisample"
' Substitute password here
Dim tokenProvider As ITokenProvider = New HTTPTokenProvider(tokenServiceUrl, username, password)
Dim baoReportHelper As New BAOReportHelper(tokenProvider)
' Define an input extent Envelope
Dim coordinates As New ExtentCoordinates()
coordinates.XMin = -117.171502
coordinates.XMax = -117.154933
coordinates.YMin = 34.052656
coordinates.YMax = 34.060632
coordinates.CoordinateSystem = "4326"
' WGS_1984 coordinate system.
' Specify extent data
Dim extent As New ExtentData()
extent.Coordinates = coordinates
' Specify parameters of StdGeographiesFromExtent task
Dim parameters As New StdGeographiesFromExtentParams()
parameters.GeoLevelID = "US.Tracts"
parameters.SpatialRelationship = esriSpatialRelEnum.esriSpatialRelOverlaps
parameters.AnalysisExtent = extent
' Get a list of all ZIP codes in the study area
Dim locations As StdGeographiesReturnedFeature() = baoReportHelper.StdGeographiesFromExtent(parameters)
' Create data layer based on the returned Census Tracts
Dim stdLayer As New StdLayer()
stdLayer.ID = "US.Tracts"
stdLayer.GeographyIDs = New String(locations.Length - 1) {}
For i As Integer = 0 To locations.Length - 1
stdLayer.GeographyIDs(i) = locations(i).FeatureID
Next
Dim dataLayer As New DataLayer()
dataLayer.StdLayer = stdLayer
' Specify report options
Dim ro1 As New ReportOptions()
ro1.ReportFormat = "PDF"
ro1.ReportHeader = Nothing
ro1.TemplateName = "dandi"
' Specify parameters of SummaryReports task
Dim reportsParameters As New SummaryReportsParameters()
reportsParameters.ReportOptions = New ReportOptions() {ro1}
reportsParameters.AreaIDField = "ID"
reportsParameters.Boundaries = dataLayer
' Execute the task
Dim result As TaskResultOutput = baoReportHelper.SummaryReports(reportsParameters)
' The result is a Demographic and Income Report of the aggregated area
' consisting of all of the U.S. Census Tracts in the input extent.
|
Example 2: Obtain a list of all U.S. Census tracts which intersect a spatial extent envelope.
Notes: Example 2 demonstrates code which consumes the BAOReport proxy class (generated from the WSDL ) without leveraging the BAOReportHelper class. Please view Example 1 above for additional information about the BAOReportHelper class.
Example (2) Code
| C# |
// Authentication: Uses Authentication proxy class to generate token. // Business Analyst Online API Sample credentials. // NOTE: These credentials are associated with an // account which constrains analysis to the // two ZIP codes in Redlands, CA. string username = "BAOAPISAMPLE"; // Substitute user name here string password = "baoapisample"; // Substitute password here Authentication auth = new Authentication(); string token = auth.getToken(username, password); // Define an input extent Envelope ExtentCoordinates coordinates = new ExtentCoordinates(); coordinates.XMin = -117.171502; coordinates.XMax = -117.154933; coordinates.YMin = 34.052656; coordinates.YMax = 34.060632; coordinates.CoordinateSystem = 4326; // WGS_1984 coordinate system. // Specify extent data ExtentData extent = new ExtentData(); extent.Coordinates = coordinates; // Specify parameters of StdGeographiesFromExtent task StdGeographiesFromExtentParams parameters = new StdGeographiesFromExtentParams(); parameters.GeoLevelID = "US.Tracts"; parameters.SpatialRelationship = esriSpatialRelEnum.esriSpatialRelOverlaps; parameters.AnalysisExtent = extent; // Associate the token with the request parameters.token = token; // Instantiate the BAOReport proxy object to submit the // request BAOReport baoReportProxy = new BAOReport(); StdGeographiesReturnedFeature[] locations = baoReportProxy.StdGeographiesFromExtent(parameters); |
Example (2) Code
| VB.NET |
' Authentication: Uses Authentication proxy class to generate token. ' Business Analyst Online API Sample credentials. ' NOTE: These credentials are associated with an ' account which constrains analysis to the ' two ZIP codes in Redlands, CA. Dim username As String = "BAOAPISAMPLE" ' Substitute user name here Dim password As String = "baoapisample" ' Substitute password here Dim auth As New Authentication() Dim token As String = auth.getToken(username, password) ' Define an input extent Envelope Dim coordinates As New ExtentCoordinates() coordinates.XMin = -117.171502 coordinates.XMax = -117.154933 coordinates.YMin = 34.052656 coordinates.YMax = 34.060632 coordinates.CoordinateSystem = 4326 ' WGS_1984 coordinate system. ' Specify extent data Dim extent As New ExtentData() extent.Coordinates = coordinates ' Specify parameters of StdGeographiesFromExtent task Dim parameters As New StdGeographiesFromExtentParams() parameters.GeoLevelID = "US.Tracts" parameters.SpatialRelationship = esriSpatialRelEnum.esriSpatialRelOverlaps parameters.AnalysisExtent = extent ' Associate the token with the request parameters.token = token ' Instantiate the BAOReport proxy object to submit the ' request Dim baoReportProxy As New BAOReport() Dim locations As StdGeographiesReturnedFeature() = baoReportProxy.StdGeographiesFromExtent(parameters) |
Example 3: Obtain a list of all ZIP codes intersecting an area described by a custom polygon.
Notes: Example 3 demonstrates code which consumes the BAOReport proxy class (generated from the WSDL ) without leveraging the BAOReportHelper class. Please view Example 1 above for additional information about the BAOReportHelper class.
Example (3) Code
| C# |
// Authentication: Uses Authentication proxy class to generate token.
// Business Analyst Online API Sample credentials.
// NOTE: These credentials are associated with an
// account which constrains analysis to the
// two ZIP codes in Redlands, CA.
string username = "BAOAPISAMPLE"; // Substitute user name here
string password = "baoapisample"; // Substitute password here
Authentication auth = new Authentication();
string token = auth.getToken(username, password);
// Define an input Polygon
GeographicCoordinateSystem gcs = new GeographicCoordinateSystem();
gcs.WKID = 4326;
gcs.WKIDSpecified = true;
PointN point1 = new PointN();
point1.SpatialReference = gcs;
point1.X = -117.150177;
point1.Y = 34.062935;
PointN point2 = new PointN();
point2.SpatialReference = gcs;
point2.X = -117.171502;
point2.Y = 34.060631;
PointN point3 = new PointN();
point3.SpatialReference = gcs;
point3.X = -117.185412;
point3.Y = 34.063170;
PointN point4 = new PointN();
point4.SpatialReference = gcs;
point4.X = -117.186903;
point4.Y = 34.043610;
PointN point5 = new PointN();
point5.SpatialReference = gcs;
point5.X = -117.160785;
point5.Y = 34.042416;
PointN point6 = new PointN();
point6.SpatialReference = gcs;
point6.X = -117.154932;
point6.Y = 34.052655;
Ring ring1 = new Ring();
// The "last" vertex should equal the "first" vertex.
ring1.PointArray = new Point[] { point1, point2, point3, point4,
point5, point6, point1 };
PolygonN poly1 = new PolygonN();
poly1.SpatialReference = gcs;
poly1.RingArray = new Ring[] { ring1 };
// Specify extent data
ExtentData extent = new ExtentData();
extent.Extent = poly1 as Geometry;
// Specify parameters of StdGeographiesFromExtent task
StdGeographiesFromExtentParams parameters = new StdGeographiesFromExtentParams();
parameters.GeoLevelID = "US.ZIP5";
parameters.SpatialRelationship = esriSpatialRelEnum.esriSpatialRelIntersects;
parameters.AnalysisExtent = extent;
// Associate the token with the request
parameters.token = token;
// Instantiate the BAOReport proxy object to submit the
// request
BAOReport baoReportProxy = new BAOReport();
StdGeographiesReturnedFeature[] locations = baoReportProxy.StdGeographiesFromExtent(parameters);
|
Example (3) Code
| VB.NET |
' Authentication: Uses Authentication proxy class to generate token.
' Business Analyst Online API Sample credentials.
' NOTE: These credentials are associated with an
' account which constrains analysis to the
' two ZIP codes in Redlands, CA.
Dim username As String = "BAOAPISAMPLE"
' Substitute user name here
Dim password As String = "baoapisample"
' Substitute password here
Dim auth As New Authentication()
Dim token As String = auth.getToken(username, password)
' Define an input Polygon
Dim gcs As New GeographicCoordinateSystem()
gcs.WKID = 4326
gcs.WKIDSpecified = True
Dim point1 As New PointN()
point1.SpatialReference = gcs
point1.X = -117.150177
point1.Y = 34.062935
Dim point2 As New PointN()
point2.SpatialReference = gcs
point2.X = -117.171502
point2.Y = 34.060631
Dim point3 As New PointN()
point3.SpatialReference = gcs
point3.X = -117.185412
point3.Y = 34.06317
Dim point4 As New PointN()
point4.SpatialReference = gcs
point4.X = -117.186903
point4.Y = 34.04361
Dim point5 As New PointN()
point5.SpatialReference = gcs
point5.X = -117.160785
point5.Y = 34.042416
Dim point6 As New PointN()
point6.SpatialReference = gcs
point6.X = -117.154932
point6.Y = 34.052655
Dim ring1 As New Ring()
ring1.PointArray = New Point() {point1, point2, point3, point4, point5, point6, _
point1}
Dim poly1 As New PolygonN()
poly1.SpatialReference = gcs
poly1.RingArray = New Ring() {ring1}
' Specify extent data
Dim extent As New ExtentData()
extent.Extent = TryCast(poly1, Geometry)
' Specify parameters of StdGeographiesFromExtent task
Dim parameters As New StdGeographiesFromExtentParams()
parameters.GeoLevelID = "US.ZIP5"
parameters.SpatialRelationship = esriSpatialRelEnum.esriSpatialRelIntersects
parameters.AnalysisExtent = extent
' Associate the token with the request
parameters.token = token
' Instantiate the BAOReport proxy object to submit the
' request
Dim baoReportProxy As New BAOReport()
Dim locations As StdGeographiesReturnedFeature() = baoReportProxy.StdGeographiesFromExtent(parameters)
|