4  Data Catalog REST

As described in Mapfluence REST Overview, a Mapfluence request may be for data returned as a map, for data returned as text, or for metadata about the Mapfluence data catalog. In each case, the source of the information returned from the query is the Mapfluence catalog. The Mapfluence data catalog is a collection of datasets, each of which is made up of one or more tables of information. The use of REST to access the Mapfluence Data Catalog is covered in the following sections:

• Mapfluence Paths and SQL
• Catalog Access via REST
• Using Geometry Tables
• Using Attribute Tables
• Using Geometries with Attributes

The Mapfluence REST API has been designed to incorporate, where possible, familiar SQL database terminology into the structure of mapping and query requests. For example, consider a request for data on EPA brownfields where air contamination was found in 2009. In SQL such a query, which would include FROM and WHERE statements, might look like this:

SELECT geometry
FROM epabrnfld.bf2009_geom
WHERE epabrnfld.bf2009.air_f = 't'

In a Mapfluence REST query, the part of the path that specifies the data source would include from and where statements like this:

from=epabrnfld.bf2009_geom|where=epabrnfld.bf2009.air_f:t

The Mapfluence REST API includes three main categories of queries used to access metadata about the contents of the data catalog:

• Dataset queries, e.g. /catalog/datasets
• Geometry table queries, e.g. /catalog/geometryTable/
• Attribute table queries, e.g. /catalog/attributeTable/

These data catalog queries allow you to discover which datasets, attribute tables, and geometry tables are available within the Mapfluence Data Catalog. In the following examples, the first query returns a list of all datasets in the data catalog, and the second query returns the metadata associated with the dataset umi.us_census00, whose display name is "Census Demographics and Boundaries":

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

http://query.mapfluence.com/2.0/MFDOCS/catalog/dataset/umi.us_census00

Notes:
» For a list of data catalog queries in each category (dataset, geometry, and attribute), as well as links to the reference for each query, see Catalog Resources at http://developer.urbanmapping.com/docs/mapfluence/rest/2.0/reference/catalog/intro.
» For a list of the available datasets in the Mapfluence Data Catalog (with each list item linking to a detailed description) see http://developer.urbanmapping.com/content/data-catalog.

Once you choose a dataset, you can drill down further to return metadata about the contents of tables and specific attributes their features. In the following example, the first query returns a list of geometry tables associated with the Census Demographics and Boundaries dataset (umi.us_census00). The second query returns a list of the feature sets of the geometry table umi.us_census00.county_geometry, which contains the polygonal geometry of U.S. counties. The third returns the geometry of a single feature (Traverse County, MN) identified by its feature ID (27155):

http://query.mapfluence.com/2.0/MFDOCS/catalog/dataset/umi.us_census00/geometryTables

http://query.mapfluence.com/2.0/MFDOCS/catalog/geometryTable/umi.us_census00.county_geometry/featureSets

http://query.mapfluence.com/2.0/MFDOCS/catalog/feature/umi.us_census00.county_geometry.27155

With the first geometry table query above we learn that within the Census Demographics and Boundaries dataset there are geometry tables for a number of different feature types:

Geometry tables like those listed in the left-hand column may be used during mapping to specify (using the from property in a layer definition) the types of areas and/or boundaries that should be displayed on a map layer.

As with geometry tables, you can also drill down into attribute tables. In the following example, the first query returns a list of attribute tables associated with the Census Demographics and Boundaries dataset (umi.us_census00). The second query returns a list of the attribute record sets of the attribute table umi.us_census00.county, which contains records on U.S. counties. The third returns metadata, in this case the Federal Information Processing Standard (FIPS) code, from the specified column (.fips) in an attribute table:

http://query.mapfluence.com/2.0/MFDOCS/catalog/dataset/umi.us_census00/attributeTables

http://query.mapfluence.com/2.0/MFDOCS/catalog/attributeTable/umi.us_census00.county/attributeRecordSets

http://query.mapfluence.com/2.0/MFDOCS/catalog/attributeColumn/umi.us_census00.county.fips

Using the metadata returned from attribute table queries enables you to identify a data source that can be specified (using the select property) in a spatial query.

Mapping often involves showing how the value of a given attribute varies among geometries. For example we might want to show how median household income (an attribute) varies depending on census tracts (a geometry). To do this we need to include two types of property definitions in our mapping path:

• The attribute whose values are to be displayed is specified with the select property, which identifies the source of the data (an attribute table).
• The geometry unit (e.g. census tract, city, county, etc.) for which the attribute values are to be displayed is specified with the from property, which identifies the source of the geometries (a geometry table).

Using our example of median household income by census tract, a thematic layer (mode=theme) displaying this information would be defined as follows, with select specifying the source of the census data and from specifying the source of the census tract geometry (the other properties will be explained in subsequent sections of this document):

/mode=theme|select=umi.us_census00.stats.med_hhinc|from=umi.us_census00.tract_geometry|breaks=200000,400000,600000,800000,1000000|colors=FFFFFF80,0000FF80,00FF0080,FFA50080,FF000080

The list of geometry tables available for a given attribute table may be discovered using the data catalog calls described in previous sections. They can also be found manually with a data catalog search at http://developer.urbanmapping.com/content/data-catalog.

Top