14  REST for Spatial Queries

Spatial queries are used for operations that don't involve mapping; instead they return text, typically JSON. These queries are distinct from data catalog queries in that they are focused on returning the actual data within the Mapfluence data catalog (or, if enabled, a custom dataset) rather than returning metadata about the catalog.

Spatial queries retrieve data related to a feature, such as a county or state, that is identified with the from property. The data to retrieve about the feature is specified with the select property, which points to one or more data sources. Each source is one of the following:

In the following sections we'll use Mapfluence REST to perform two different kinds of spatial queries:




14.1  Expression Spatial Querygo:  top

The following steps illustrate how to specify a simple spatial query using an expression. In this case the query returns a count of the states whose name contained the string "al" as of the specified date:

1.  Start with the host, version, and API key (substitute your own key):

http://query.mapfluence.com/2.0/MFDOCS

2.  Add the query statement:

/spatialquery.json

3.  Add the query definition in the form of a query string, in this case specifying the following properties:
- from=umi.us_census00.state_geometry: the geometry table containing the features (in this case states) about which the data is to be retrieved.
- select=count(*): the data to retrieve, in this case a count (a form of aggregate expression) of the rows in the attribute table that meet the criteria specified with the where property.
- where=name__icontains:'al': an optional filter that may be applied to narrow the results returned from the query. In this case we want the count to include only states with "al" in the field of the attribute table column "name."
- date=2010-08-01T07:00:00Z: The datetime for which the information is retrieved (if a new state had been added to the Union after August 1, 2009 at 7AM local time, it would not be counted in this query).

?from=umi.us_census00.state_geometry&select=count(*)&where=name__icontains:'al'&date=2010-08-01T07:00:00Z

4.  Put all the pieces together and you have the complete REST path for the query:

http://query.mapfluence.com/2.0/MFDOCS/spatialquery.json?from=umi.us_census00.state_geometry&select=count(*)&where=name__icontains:'al'&date=2010-08-01T07:00:00Z

This query returns the following JSON key/value pair (to see the complete response body, open a browser window and enter the URL into the address field):

{
  "count(*)": 3
}

Notes:
» For information on selecting data to retrieve from the three types of sources see Retrieve data with select statements at http://developer.urbanmapping.com/docs/mapfluence/rest/2.0/guides/select/.
» In a where statement (filter), two underscores "__" separate the attribute or field (e.g. name) and the operator (e.g. icontains).
» For information on the filters that may be used in queries see Filter data using where statements at http://developer.urbanmapping.com/docs/mapfluence/rest/2.0/guides/where.
» For information on using dates in queries, see Dealing with dates at http://developer.urbanmapping.com/docs/mapfluence/rest/2.0/guides/dates.
» For complete details on the purpose and valid values of spatial query properties, both required and optional, refer to the /spatialquery.json page of the Mapfluence REST API Reference at http://developer.urbanmapping.com/docs/mapfluence/rest/2.0/reference/query/SpatialQuery.




14.2  Attribute and Field Querygo:  top

The following steps illustrate how to specify a spatial query using an attribute and two feature fields. In this case the query returns the names and centroid coordinates of U.S. counties in which average annual snowfall exceeded 100 inches as of the specified date:

1.  Start with the host, version, API key (substitute your own key), and query statement:

http://query.mapfluence.com/2.0/MFDOCS/spatialquery.json

2.  Add the query definition in the form of a query string, in this case specifying the following properties:
- from=umi.us_census00.county_geometry: the geometry table containing the features (in this case counties) about which the data is to be retrieved.
- select=umi.snowfall_monthly.attributes.annualavg, centroid, name: the data to retrieve about the features (counties), in this case the average annual snowfall attribute (from an attribute table with data on snowfall), and the feature fields name and centroid (coordinates of the geographical center of the county).
- where=umi.snowfall_monthly.attributes.annualavg_gt:100: an optional filter that may be applied to narrow the results returned from the query (thereby avoiding the error TooManyResultsError). In this case we want the count to include only counties where average annual snowfall is greater than 100 inches.
- date=2010-08-01T07:00:00Z: The datetime for which the information is to be retrieved (August 1, 2009 at 7AM local time).

?from=umi.us_census00.county_geometry&select=umi.snowfall_monthly.attributes.annualavg,centroid,name&where=umi.snowfall_monthly.attributes.annualavg__gt:100&date=2010-08-01T07:00:00Z

3.  Put the pieces together and you have the complete REST path for the query:

http://query.mapfluence.com/2.0/MFDOCS/spatialquery.json?from=umi.us_census00.county_geometry&select=umi.snowfall_monthly.attributes.annualavg, centroid, name&where=umi.snowfall_monthly.attributes.annualavg__gt:100&date=2010-08-01T07:00:00Z

This query returns a FeatureCollection JSON array of 44 features (counties) meeting the specified criteria. The following example shows the array member for the first county in the list, which gives the county's centroid (a point geometry), its average annual snowfall, and its name (to see the complete response body, open a browser window and enter the URL into the address field):

{
  "geometry": {
    "type": "Point",
    "coordinates": [
      -89.514786,
      46.0529009
    ]
  },
  "type": "Feature",
  "properties": {
    "umi.snowfall_monthly.attributes.annualavg": 144.1,
    "name": "Vilas"
  }
}

Note: See query-related notes above.

Top