Data Manager 101

Using the Data Manager and Search APIs

This guide will describe the steps to create a table in the Data Manager API so that you can use the Search API to allow your applications to find appropriate geographic objects meeting specific geographic criteria.

Note: If your key was created on or after June 23, 2015, you do not need to submit a LEGACY_CLIENT_ID or CONSUMER_SECRET. These parameters can be omitted. "LEGACY_CLIENT_ID or CONSUMER_KEY" means to use the LEGACY_CLIENT_ID if the key was created before June 23, 2015 and CONSUMER_KEY otherwise.

1. Get data

   
   The data you want to search and/or display needs to be in a format that the Data Manager API can handle. You can upload a csv, kml, or zipped Shapefile. Below is a sample csv file including locations for the Denver Public Library.
   

   name,address,phone
   Central Library,10 W. Fourteenth Ave. Pkwy. 80204,720-865-1111
   Athmar Park Branch Library,1055 S. Tejon Street 80223,720-865-0230
   Ross-Barnum Branch Library,3570 W. First Avenue 80219,720-865-0145
   ...

   
   The file is available for download below. Make sure to include a header row with your column names. This very simple csv includes columns for name, address, and phone. You can create up to 150 column names to appropriately describe the data you wish to pull from the Search API and/or display on a map.

2. Create a table

   Create a Data Manager API post request to create your table given your header row and data types.
   The create-table request url requires your key.
   http://www.mapquestapi.com/datamanager/v2/create-table?key=[CONSUMER_KEY]
   The post data of the request will include your legacy clientId, consumer secret, table name, and columns. Your table is made up of the mqap prefix and your legacy clientId or key followed by any name you choose for your table. This name will be included in the hostedData parameter in your Search API request. Your list of columns will be made up of name and type parameters. Available field types can be found with the get-column-types response.

   {
   	"clientId":"[LEGACY_CLIENT_ID]",
   	"password":"[CONSUMER_SECRET]",
   	"tableName":"mqap.[LEGACY_CLIENT_ID or CONSUMER_KEY]_DenverPublicLibrary",
   	"columns":[
   		{"name":"name","type":"String"},
   		{"name":"address","type":"FullAddress"},
   		{"name":"phone","type":"String"}
   	]
   }

   or

   <datamanager>
   	<clientId>[LEGACY_CLIENT_ID]</clientId>
   	<password>[CONSUMER_SECRET]</password>
   	<tableName>mqap.[LEGACY_CLIENT_ID or CONSUMER_KEY]_DenverPublicLibrary</tableName>
   	<columns>
   		<column>
   			<name>name</name>
   			<type>String</type>
   		</column>
   		<column>
   			<name>address</name>
   			<type>FullAddress</type>
   		</column>
   		<column>
   			<name>phone</name>
   			<type>String</type>
   		</column>
   	</columns>
   </datamanager>

   The sample has an address field that is type FullAddress. When the Data Manager receives this type it will automatically geocode it and insert the results into the mqap_geography column. It will also fill the mqap_quality column with the geocode quality code.

3. Load the table with data

   Load the newly created table with the csv file with the upload-data request. Again, the url requires your application key. 
   http://www.mapquestapi.com/datamanager/v2/upload-data?key=[CONSUMER_KEY]
   The post data of the request will include your legacy clientId, consumer secret, table name, and append parameter indicating whether you want to append the uploaded data to the existing table data or replace the existing table data.
   

   {
   	"clientId":"[LEGACY_CLIENT_ID]",
   	"password":"[CONSUMER_SECRET]",
   	"tableName":"mqap.[LEGACY_CLIENT_ID or CONSUMER_KEY]_DenverPublicLibrary",
   	"append":false
   }

   or

   <datamanager>
   	<clientId>[LEGACY_CLIENT_ID]</clientId>
   	<password>CONSUMER_SECRET]</password>
   	<tableName>mqap.[LEGACY_CLIENT_ID or CONSUMER_KEY]_DenverPublicLibrary</tableName>
   	<append>false</append>
   </datamanager>

   The post data will also include your file. Depending on the size of the file upload, the process may take a second to several minutes. If a Geography type field is present in the table and contains valid data, the Data Manager will not geocode the location. It will insert the user provided latitude and longitude value. If Latitude and Longitude data type cells have valid values, they will be used to fill the mqap_geography value. Finally, the Data Manager will add a mqap_id value to the record to store a unique table reference for each record.

4. Search

   Once the data is loaded, you can use the Search Web Service to access your new data. Here is a simple search request for the library data near the center of Denver, CO.
   http://www.mapquestapi.com/search/v2/radius?key=CONSUMER_KEY]&origin=Denver,+CO&radius=1&hostedData=mqap.[LEGACY_CLIENT_ID or CONSUMER_KEY]_DenverPublicLibrary
   The simple radius search request includes your key, an origin, radius, and the hostedData parameter which includes your table name.

A Data Manager user interface/sample application is available that allows you to perform these functions within a simple application along with several other functions. It allows you to create, view, copy, and delete tables, create, upload, add, delete, search, and change data. It is a JavaScript based sample application that is there as a basis for other applications. Take the code and run with it.