SpatialQuery

SpatialQuery retrieves features from geometry datasets:

  • Get counties within 10 miles of a point
  • Get states with unemployment greater than 9%
  • Get zip codes and their average July temperture

or retrieves a data summary:

  • Get the average household income in California counties.
  • Get the sum of population of zip codes within a polygon.

This document is a overview of the SpatialQuery: see SpatialQuery syntax for details and more examples.

Requests and Responses

SpatialQuery borrows its parameter names from SQL. URLs have the following arguments:

  • from
  • select
  • aggregate
  • where
  • order_by
  • between
  • limit
  • offset

SpatialQuery returns a JSON or GeoJSON list of features, or a JSON object containing data summary results.

See an Example JSON result or Example GeoJSON result for all US Counties with a population greater than 3,000,000 people.

Specifying Geometry Sets

You must specify what geometry set(s) (e.g. US Census Counties) you want in the from argument.

Selecting Data

By default, SpatialQuery returns features with all their built-in fields.

In the select argument, you can limit the built-in fields that are returned (for performance reasons) or select from attribute datasets. For example, to select US Census per capita income:

us_census00.stats.av_pci

See the data catalog for available datasets.

Filtering Data

You can filter results by geometry or data criteria using the where argument.

Geometry filters allow you to retrieve features whose geometry meets spatial critera (i.e. within 10 miles of some point, or 95% contained by some polygon).

Data filters filter your results by "built-in" and/or attribute fields. For example, you might retrieve features with population greater than 100, or counties with US Census household count greater than 25,000.

Limiting the Result Set

Limit and offset work just like their SQL equivalents. For any query, SpatialQuery returns a maximum of 100 results.

Ordering Results

Order_by allows you to order results by built-in or attribute fields.

Getting a Data Summary

A data summary works like SQL aggregates, returning a single summarizing every feature matching the request. For example, you might request the average population of features:

AVG(population)

To get a data summary, use the aggregate argument rather than select.

Dealing with Temporal Data

All Mapfluence attribute data records have a period -- a timeframe when the data is "current". For example, the 2000 US Census is current from 1/1/2000 to 12/31/2009.

The between clause specifies what date range you want to select data from. If you omit the between clause, Mapfluence defaults to the dataset's current period, as selected by Mapfluence staff.

It is also possible to specify periods per attribute dataset in select.