The following sections provide a general foundation for using Mapfluence via REST:
| 1.1 About Mapfluence REST | go: top |
Mapfluence 2.0 REST API provides access to Mapfluence via a RESTful HTTP interface. The interface includes resources for mapping, spatial queries, and access to the Mapfluence data catalog. The REST capabilities are a subset of the JS capabilities. Use of the REST API requires building an application around it to perform tasks such as constructing requests and handling responses.
A thorough explanation of REST (Representational State Transfer) architecture and practices is beyond the scope of this document. Ample information about REST is available on the Internet. For example, a helpful overview from IBM may be found at http://www.ibm.com/developerworks/webservices/library/ws-restful/. A familiarity with HTTP/REST vocabulary such as resources, requests, and responses is required to take full advantage of the information in the following sections.
In addition to general REST/HTTP knowledge, using Mapfluence through a RESTful HTTP interface requires familiarity with a number of Mapfluence-specified REST details, including Resource Path and Collections. These topics are covered in the Mapfluence REST guide at http://developer.urbanmapping.com/docs/mapfluence/rest/2.0/guides/rest.
Note: Important additional concepts related to working with REST in Mapfluence are covered in Mapfluence REST Topics.
| 1.2 Mapfluence Mapping REST | go: top |
A Mapfluence map combines a base map layer, which is a basic representation (land, water) of the area being mapped, with one or more additional overlaid layers displaying geographically-correlated information about that area. The information typically comes from the Mapfluence Data Catalog, though custom data catalogs may also be used. A searchable list of the available datasets in the Mapfluence Data Catalog (with each list item linking to a detailed description) is available at http://developer.urbanmapping.com/content/data-catalog.
Maps are generated in response to a mapping request from a client. The request specifies the area to be included and selects the features (objects or events) to be represented on each overlaid layer. Mapping requests involves calls to the following three Mapfluence objects:
In the REST approach, a mapping request takes the form of an HTTP GET. The path of the request is parsed by the Mapfluence server to determine what data the map's layers each represent, the order (front to back) in which they will be composited, how their graphical elements are to be rendered (colors, opacity, icons, font size, etc.), and the base map (Mapfluence, Bing, Google, etc.) onto which the layers will be overlaid. Mapfluence retrieves the specified data for each layer from the data catalog, builds the layers into a map, and renders a selected portion of the map as an image tile that is returned to the client in the HTTP response.
| 1.3 Mapfluence Query REST | go: top |
Mapfluence queries return one of the following types of information:
The basic concept of these queries is the same as for a map, meaning that a REST query takes the form of an HTTP GET, and the path of the request is parsed by the Mapfluence server to determine what data to return to the client. Unlike a mapping operation, however, results are returned in the form of text rather than as a map. Depending on the query and the type of data requested, the data is returned as JSON (for /estimate, /spatialops, /catalog, and sometimes for /spatialquery) or as GeoJSON (for /geocoder and sometimes for /spatialquery; see http://GeoJSON.org/).
Note: A searchable list of the available datasets in the Mapfluence Data Catalog (with each list item linking to a detailed description) is available at http://developer.urbanmapping.com/content/data-catalog.