What you need to understand

You don't need to be a hard-core programmer to use the simplest pieces of Mapfluence, but you do need at least some of the programmer's formal, procedural approach to problems. If you want to use more than the simplest pieces, you will need to understand how to code. (Fortunately, if you do code, our Javascript API aims to be dirt simple, and our Webservice APIs allow you to almost anything.)

You do not need to know much about Graphical Information Systems, but you do need to know what a latitude and a longitude are if you want to do advanced work. At some point, it is likely that you will want to specify a geometry using Well-Known Text (WKT) markup.

If you are going to work with data based on areas of the US, it might be helpful to understand what the census calls census tracts, census block groups, and places.

If you are going do advanced analysis with the QueryAPI, you will need to know understand JSON and the GeoJSON data formats.

For advanced work, want to know basic SQL. Our Query API documents assume that you know at least enough to be able to tell what the following SQL statement does:

SELECT parents.name, kids.name
FROM parents JOIN kids
ON kids.parent = parents.id
WHERE parents.gender = 'F';

Now, even if you are a uber-geogeek who exports shapefiles from ESRI tools, reprojects them into Lambert Conical Conformant, imports them into PostGIS, and populates an OpenLayers map with them, blindfolded, uphill, in the snow, you still need to read the docs. It will be worth it.

What tools you need

• A modern browser with Adobe Flash Player 9 or higher. We have tested on Firefox 3, Internet Explorer 7+, Chrome, and Safari.
• If you are working with any of the APIs besides the Visual API, you will probably find life easier with a JSON browser plug-in. We recommend the JSONView plugin for Firefox.
• To do development (beyond the lab), you need to have a developer key. Send email to support@urbanmapping.com and explain who you are and why you want a key.

Visual API

The Visual API calls produce maps and imagery. You tell Mapfluence how you want things to look, and Mapfluence will render maps any way you want them to look.

There are two web services in the Visual API:

Visual API - The Visual API renders Mapfluence data into map tiles flexibly, colorfully, and quickly. For the nuts and bolts of this service, see the Visual API Syntax.

EasyMap web service - EasyMap builds a Web page that has a simple map on it from the parameters you give it. EasyMap lets you show your map using your choice of several different mapping frameworks, including Google Maps, Bing Maps, and OpenLayers. If, for example, your VP of Sales just wants to see once what the median age in Pittsburgh and suburbs is, this is the service to use.

Query API

The Query API lets you query our spatial data warehouse and get JSON (or GeoJSON) objects back. You can then use the data in a non-map way: present the data in another way (i.e. a chart, table, query your own db) or perform more complex data reduction.

SpatialQuery is the workhorse of the Query API, and it is the one we expect people to use most. It is very much like a SELECT statement that you would use in SQL. This will enable you to, for example, create a chart showing the percentage of Democratic votes in U.S. presidential elections for all counties with more than 10% senior citizens.

EstimationQuery takes an attribute that is given by one geometry type and estimate what that attribute's value is in some other geometry type. If, for example, the governor wants to know how many people in the state live on a flood plain, this is the query to use.

SpatialJoin performs joins (in the SQL sense of 'join') between two geometry sets. For example, if you want to know the names of all US counties which have coastlines with steep slopes, SpatialJoin can use spatial predicates to join county geometries with the USGS coastal vulerability geometries.

FeatureQuery retreives information about a geometry from its unique identifier. This is highly useful in debugging. If, for example, you are trying to figure out why your bonehead predecessor hardcoded geometry id 8727362 into the code, FeatureQuery will answer that.

Data Sets and the Data Catalog

Mapfluence backend has a huge corpus of curated spatial and spatially associated data. This data is organized into Data Sets - a collection of related data. For example, the US Census 2000 Cartographic Boundaries is a data set that includes numerous area definitions (states, counties, ZIP codes, etc) and their associated data. The USGS Coastal Vulnerabilty to Sea Level Rise is another data set, with both geometry features and attributes (i.e. classifications of risk). Each dataset may include multiple geometry sets and/or multiple attribute tables (defined below).

You can view everything - all the metadata - about Data Sets the in Data Catalog. And if there is a collection of data you don't see but want; send us an email.

Geometry Sets and Features

Geometry sets are collections of features -- conceptual locations (like states, roads, or fire stations) that have geometries (polygons, lines, or points) as an intrinsic part of the feature. Fire stations don't exist in the abstract, roads are almost always defined by their locations, and states have well-defined boundaries.

If you wanted to use Mapfluence to make a map of county boundaries, you would only need to access the county geometry set.

Attributes and Attribute Tables

Attribute tables have records which themselves are not geometries, but which are associated with specific geometry types like counties, neighborhoods, roads, or tornado paths. For example, one Mapfluence attribute table has records with information about the 2000 US Census tabulated by state, county, ZCTA, tract, and block group.

Each record has a number of attributes like the median age of the state, the number of people under age 5, etc. The number of people under age 5 in Texas is is not something intrinsic to Texas-ness. (All the children could leave Texas next year, and it would still be Texas.) However, it is clearly associated with Texas. (In geek-speak: attribute table records have HAS-A relationships with geometry features.)

Each record in an attribute table thus corresponds to one specific geometry, like "Texas", "Santa Clara County", "Interstate 80", or "Kenya".

Geometry Fields

In addition to attributes, every geometry has some standard built-in data fields: id, name, area, centroid, and a few others.

Note: to reduce confusion between data columns in geometry sets and data in attribute tables, we always call a column in a geometry set a "field" and a column in an attribute table an "attribute".

Periods (optional)

Some of datasets have data for multiple time periods -- named timespans where the data is valid (or perhaps "most valid"). You are not obliged to specify a period -- every dataset has a default period, usually the most recent version of the data -- you can if you want.

For example, UMI has data from the US Center for Disease Control on birth rates by county for the years 2000, 2001, 2002, 2003, 2004, 2005, and 2006. When there is such temporal data, you can choose a specific time period or time periods. You could choose to see the data from 2004. You could choose to see the data from 2006. You could choose to see the data from 2000-2003. You could also choose to see the data from 2000, 2002, 2004, and 2006.

Specifying attributes

If you wanted to color the states of the US based on the number of children under 5, would need to specify both the geometry set (counties) and the attribute table (us census bureau). How do you find datasets? What do you call them? How do you find the names of attributes?

To find a dataset, look in the Mapfluence Data Catalog.

Mapfluence's large set of curated data is constantly growing, but you can see from the Mapfluence Data Catalog what is currently available to you. If you have not signed up for a Mapfluence account and are not logged in, not all of the data will be available to you. E.g.:

http://developer.urbanmapping.com/mapfluence/datacatalog/datasets/us_census00/

You can see the US Census dataset has multiple attribute data tables and multiple geometry sets.

All entities in Mapfluence are given canonical proper names (e.g. "US Census Summary File 1", "Airport Routes", "XYZ Population Segmentation", etc.), these are long and tedious to type. Thus we give all entities short code names to refer to that object. Objects that are contained in other objects have a fully-qualified name that includes all of the parent nodes, so for the attribute

uselect_pres.county_data.write_in_votes

• uselect_pres is the code name of a dataset,
• county_data is the code name of an attribute table, and
• write_in_votes is the name of an attribute in that attribute table.

For example, if you open the "U.S. Presidential Elections" dataset, you will discover a Data Table named "U.S. Presidential Elections By County Table", which has a number of different attributes. You'll the code name after the canonical name in parentheses, e.g.:

Total Write-in Votes (uselect_pres.county_data.write_in_votes)

Total Votes for a candidate whose name did not appear on the ballot

You will also need the name of the geometry set that is associated with that data. These are listed at the top of the page for each table, with their code names in parentheses.

US Census 2000 County and County Equivalent Boundaries (us_census00.county_geom)

(Hint: most of the time, if you are using an attribute table which reports data for an area of the US, you will want one of the Census Bureau geometries: states, counties, census tracts, ZIP codes, places, or census block groups.)

Specifying the geometry set

Almost always when issuing an API query, you will need to specify a geometry type. For example, if you are plotting media income by county, you have to tell the API that you want county geometries.

They way you do that is by specifying the code name for a geometry set, also found in the Data Catalog

Under US Census dataset , you will see a section labeled Geometry Tables, and under that you will see a number of geometry sets. If you look at the county geometry set, you will see a code name us_census.county_geom. That is the name you will use to tell Mapfluence that you are working with counties and not states, zip codes, or any other type of area.

Specifying features

Each feature has an id that is unique inside all of Mapfluence. This means two things:

1. You can use a feature of one type even if the rest of the API call uses a different feature type. For example, you can not only query for all the counties with median age over 55, but you can also query for all the counties with median age over 55 that are contained by geometry ID 576399 (Texas).
2. You can distinguish between places that have the same name. You can cleanly specify Washington County, AL (id 573188) without having to write a bunch of code to distinguish between the 31 different Washington Counties in the US.

Another way of specifying features is by using Well-Known Text format descriptions of geometries. For example, you can query for all the counties with median age over 55 that are in the continental US and (roughly) west of the Mississippi River by adding a filter to check for containment in the polygon 'POLYGON((-90 25,-130 25,-130 50,-90 50,-90 25))'.

To find out which feature has which id and vice versa, look at the FeatureQuery documentation.

Specifying geometry fields

Because each record has only one geometry associated with it, geometry fields do not need to be fully-qualified with the name of the dataset and geometry set.

Specifying periods

The Data Catalog information for a table will also tell you what your options are for time periods. Look for information labelled under the heading "Data Period".

Like geometry features or attributes, periods have code names (like "1999" or "2009-07"). The catalog page will have information on description, start times and end times, helpfully named description, start and end.