URL Escaping

SpatialQuery URLs contain special characters that should be URL-escaped. See the guide to URL escaping.

Examples

The examples on this page should give you a good guide to how to use SpatialQuery. Examples show only the query arguments, without the Base Path, split onto multiple lines for readability. Note that the examples are not URL-escaped, so they may not work exactly as written in URLs.

Base Path

The base path for SpatialQuery requests is:

http://spatial.mapfluence.com/spatialquery.<format>

where <format> is either json or geojson and specifies the reponse format.

from (required)

The from clause specifies what geometry datasets to select from. Geometry datasets are specified as "<dataset.geometryset>". The data catalog provides a full list of available geometry datasets.

from=us_census00.blkgrp_geom
where=intersects([417817,417822])

See it in action

It is also possible to select from multiple geometry datasets:

from=us_census00.place_geom;us_census00.county_geom
select=name
where=contains_pct('POLYGON((-87.218 33.104,-87.513 32.964,-87.764 32.765,-87.218 33.104))',0.5)

See it in action

select

By default, SpatialQuery returns data for all of the built-in fields of features. You can choose to add additional attribute date to the response and/or limit the built-in fields that will be returned.

Limiting the field list can be a powerful tool for improving performance. Specifically, it is good not to select the geometry field if you don't need it. To limit what built-in fields are returned, simply put the fields that you do want in select:

select=id;name
from=us_census00.county_geom

See it in action

To select attribute data, put the fully qualified field name (as "dataset.table.field", which you can look up in the data catalog) in select:

select=uselect_pres.state_data.rep_pty_votes
from=us_census00.state_geom
where=name:'Florida'

See it in action

It is also possible to select attribute data from specific period(s):

select=obesity.data@2001.pct_obese
from=us_census00.state_geom

See it in action

And multiple periods:

select=obesity.data@[2001,2005].pct_obese
from=us_census00.state_geom

See it in action

Or to select multiple fields from the same attribute table in one statement:

select=obesity.data@[2001,2005].[pct_obese,pct_owght]
from=us_census00.state_geom

See it in action

If you do not specify a select clause, or specify only attribute (non built-in) fields, Mapfluence will return all of the built-in fields.

aggregate

Use the aggregate argument instead of select to get a data summary rather than a list of features. Because of this, you cannot use both a select clause and an aggregate clause in the same request.

The syntax is:

aggregate=<OPERATOR>(<operand>)

For example, if you want to find out how many counties in the US are named "Washington", you would use a query like this:

aggregate=COUNT(*)
from=us_census00.county_geom
where=name:'Washington'

See it in action

To get the minimum percent of people not in the labor force in US Census places:

aggregate=MIN(us_census00.stats.pct_nilf)
from=us_census00.place_geom

See it in action

Note that you while you can use as many aggregators as you want on any combination of the built-in fields and one attribute dataset, you can't aggregate from multiple attribute datasets in the same request. This means you can do

aggregate=COUNT(*);SUM(area);AVG(uselect_pres.county_data.uselect_pres.county_data.prt_mccain_votes)
from=us_census00.county_geom
where=name:'Washington'

See it in action

but the following will give you an error:

aggregate=AVG(uselect_pres.county_data.uselect_pres.county_data.prt_mccain_votes);AVG(unemplmnt.data.unemplevel)
from=us_census00.county_geom
where=name:'Washington'

See it in action

where

The where clause filters results by data and geometry criteria.

where=<operator>(<geometry>[,<value>])

where=intersects('RANGE(10mi POINT(-122.398939 37.776702))')
select=name
from=us_census00.zcta_geom

where=<field>__<operator>:<value>

where=unemplmnt.data.unemplevel__gte:9+intersects('RANGE(10mi POINT(-122.4 37.8))')
select=geometry;name
from=us_census00.place_geom

order_by

The order_by clause is just what you'd expect if you are familiar with SQL: it tells which field to use as a sort key for ordering the results. (In other words, the record where the sort key is numerically lowest will be first and the record where it is highest will be last.)

For example:

order_by=healthcvrg.uninsured.cnt_u_1864
select=name
from=us_census00.county_geom
where=intersects('RANGE(10mi POINT(-122.436033 37.759749))')

See it in action

will retrieve counties ordered by the count of uninsured people. You can order the results in descending order by prepending '-' to the field:

select=name
order_by=-healthcvrg.uninsured.cnt_u_1864
from=us_census00.county_geom
where=intersects('RANGE(10mi POINT(-122.436033 37.759749))')

See it in action

between

Each UMI dataset has a named period where it is valid, and you can specify the time period that you are interested in. (This prevents you from getting results from both the 1990 census and the 2000 census.)

The period name is specific to a table. For example, the US Census runs every ten years, so the US Census dataset has a period named "2000" that is defined to run from 1 Jan 2000 to 31 Dec 2009. Check the Data Catalog in the Mapfluence lab for the definition of periods for that data set (look near the bottom of the dataset's Data Tables page).

The between clause lets you specify a date (really a date/time) or date range for the data you want to select. A date will get the period that applied on that date, and a date range will get data from whatever periods overlap that date range.

Dates have the following format, and date ranges are separated by '-':

YYYY[ MM[ DD[ HH[ MM[ SS]]]]]

between=2002 03 04-2006
select=obesity.data.pct_obese
from=us_census00.state_geom

See it in action

limit

The limit clause acts much like a LIMIT clause in SQL: the value specifies how many records will be returned. For example, this query is limited to three records:

limit=3
from=us_census00.zcta_geom

See it in action

Limit, if provided, must be between 1 and 100. The default is 100.

offset

Offset works like its SQL equivalent. By performing multiple requests with different offsets, you can retrieve all results from a query that contains more than 100 features.

ashtml

The ashtml argument is useful for debugging. It formats the JSON or GeoJSON output as html such that it can be easily read in a web browser.

ashtml=1
from=us_census00.zcta_geom
limit=3

See it in action