OpenAPI QuickStart Guide
|
Installation & Generating First Map After signup, you received a unique key in your email - You will need to add this key to the <SCRIPT> tag that pulls the OpenAPI JavaScript library into your page. To add a map to your page, follow these basic steps:
Step 1: Create a basic HTML page.
Step 2: Inside the <HEAD> area, paste in the following snippet to include the OpenAPI JavaScript library. <script src="http://web.openapi.mapquest.com/oapi/transaction?request=script&key=YOUR_KEY_HERE" type="text/javascript">
a. Update the Key variable (YOUR_KEY_HERE).
b. Create a DIV tag to house the map control. c. In JavaScript, create a MQMap object and pass in the ID of the DIV tag. d. To show the map, call the .getMap() function of the MQMap object. The following code snippet demonstrates these steps (remember to replace the key!) (Page can be seen HERE)
Adding Points & Auto-Geocoding There are two main ways to add points to a map. Both are covered here, and are very similar. To add a point to the map, follow these basic steps:
Step 1: Create a new MQLocation object.
Location Properties - Address vs Latitude & LongitudeStep 2: Set its location properties (two ways to do this - see below). Step 3: Set its appearance properties (two ways to do this - see below). Step 4: Add the location object to the MQMap control's locations sub-collection (.locations.add()). Step 5: call MQMap's getMap() function to re-update the map. If you know the geographical co-ordinates of the point, you can just use the .setLatitude() and .setLongitude() functions. Otherwise, you can set as much of the address of the location as you know and OpenAPI will do its best to work out the location for you. (use the .setAddress(), .setCity(), .setStateProvince, .setPostalCode, and .setCountry() functions - we assume the country is "US" by default). Appearance Properties - Server-Side vs. Client-Side Icons Server-side icons are actually embedded inside the map, and are selected from a pre-existing catalog of icons. You tell the OpenAPI which icon to use by providing its listed ID number (the .setIconId() function). The full list of these icons is contained within the downloadable OpenAPI User's Guide PDF from the MapQuest Technical Resource Center (https://trc.mapquest.com) - login using the user name and password created when you signed up for OpenAPI, and go to the documentation section. Client-side icons are those that you have created and are hosting yourself. You tell the OpenAPI where the icon is using the .setIconSource() function. The following chunk of code demonstrates examples of all the above steps and options. (Page can be seen HERE)
The first location added to the map (loc1) uses the address of the location and a server-side icon (icon ID 203, which is the wine-glass icon). The second location uses only latitude and longitude for position, but uses a client-side icon for display - in this case a GIF housed on the same server as the HTML page itself. Routing Adding a route to your page is very similar to adding a map. Assuming you already have a basic HTML page and the OpenAPI <SCRIPT> tag installed, the steps are as follows:
Step 1: Create a DIV tag that will house the maps and maneuvers. In the example below, we called it "myRoute".
*NOTE* - Client-side icons do not work on route maps, only server-side icons .i.e: use .setIconId(), not .setIconSource().Step 2: In JavaScript, create an MQRoute object and hand it the name of the DIV tag. Step 3: Add two MQLocation objects to the MQRoute object. *NOTE* - this is different to MQMap.locations. The MQRoute object has two pre-defined MQLocation objects already attached to it.
• Define the start location using MQRoute.origin. Step 4: Call MQRoute's doRoute() function to generate the route overview map, and the list of maneuvers with their thumbnail maps.• Define the end location using MQRoute.destination. You can either populate these two objects directly (like the mqRte.origin in the example below) or you can pass in an already existing MQLocation object (such as the mqRte.destination in the example below). The following chunk of code demonstrates examples of all the above steps and options. (Page can be seen HERE)
Skinning the Map & Map Styles There are two very easy ways to change the appearance of the maps.
- The Map Skin is all the controls - the zoom bar and the pan controls around the edge of the map itself (e.g.: are they blue or green)
The following chunk of code provides a quick demonstration of using these two functions (Page can be seen HERE)- The Map Style is the actual visible appearance and style of the map itself. (e.g. is it "European")
• To set the map Skin, use the MQMap.setSkin() function. The available skin colors are listed in the full documentation. • To change the map style use the MQMap.setMapStyle() function. The available map styles are listed in the full documentation.
The RESTful Geocoding Service There are two ways to geocode with MapQuest OpenAPI. One is through the JavaScript API using the MQGeocode object (when you add addresses to the map, it happens automatically.) The other is a separately available REST service. To receive an XML-formatted geocoded response of a location, all you need to do is pass in the right parameters as part of a querystring. For Example, the following URL, if pasted directly into a browser address bar will return a geocode response:
This URL breaks down to the following name/value pairs:
This will generate an XML Return document. To understand the XML formatting, please see the full documentation guide. Hopefully you are now well on your way to embedding MapQuest maps into your website. For additional features & functions, or for any other help, please visit the documentation and forums area at https://trc.mapquest.com |
 |