Customization of MapQuest Services

1. Introduction

The MapQuest SiteAdvantage web service is to be used for the Store Locator function used for all Zale Corporation brand sites. Store Locator is used to get of map of Zales stores near a user defined address, and the driving directions from that address to the Zale store. MapQuest has upgraded the technology used for integration of maps, driving directions and locations into application. The technology presently being used will not be supported after December 2006.

2. Preparing Data

The store data is uploaded to MapQuest. It must be in a comma delimited text file (.txt extension), with double quotes around every text value. For the format of the data, refer to chapter 5 of the MapQuest Data Manager user guide.

The following table contains the fields with example values:

Field name / Example Value / Comments
RecordId / 1323 / Record ID of the store – This is a random generated number. It should be unique for each record.
Mall / ORLAND SQUARE
Street Address / 128 ORLAND SQUARE MALL
City / Orland Park
County / Cook
State / IL
Zip / 60462
Country / US
Icon ID / 31 / Choose from any Icon ID on page 145 of SiteAdvantage Developer Guide.
Display Type / To be left blank, populated by MapQuest automatically.
Latitude / To be left blank, populated by MapQuest automatically.
Longitude / To be left blank, populated by MapQuest automatically.
Goecode Quality / To be left blank, populated by MapQuest automatically.
Phone / 708 349 1490 / This is first user field; we can give a total of 10 such user fields.
StoreId / 02116 / At present, this field is not used. It can be displayed along with other store information.
8 User Fields and 20 Search Fields / All the fields are to be left blank (there will be 29 commas between the field for storeId and field for the brand)
Brand / Bailey / There will be just one store data file for all the brands. The value of this column needs to be changed based on the brand. Its value will be the value of text1 parameter in file map_search_query.
Field name / Example Value / Comments
IsDesigner / 1 / This value will be 1 if brand field is Bailey and store is to be searched for a particular designer. The value of this field will be the value of text2 parameter in file map_search_query.
Designer / Aaron Basha / There field will contain the name of the designer. This field should have a value only if the brand field is Bailey.

The following is an example record for this file, when brand is Bailey and designer name is Aaron Basha.

"1323","OAKBROOK CENTER","110 OAK BROOK CENTER","Oak Brook","Dupage","IL","60523","US","31",,,,,"630 572 8570","02116",,,,,,,,,,,,,,,,,,,,,,,,,,,,,"Bailey","1","Aaron Basha"

The following is an example record for this file, when brand is Bailey.

"1215","FASHION SHOW MALL","3200 LAS VEGAS BLVD SOUT","Las Vegas","Clark","NV","89109","US","31",,,,,"702 731 3355","02048",,,,,,,,,,,,,,,,,,,,,,,,,,,,,"Bailey","0",

The following is an example record for this file, when brand is Zales.

"6","ORLAND SQUARE","128 ORLAND SQUARE MALL","Orland Park","Cook","IL","60462","US","31",,,,," 708 349 1490","00030",,,,,,,,,,,,,,,,,,,,,,,,,,,,,"Zales",,

The following is an example record for this file, when brand is Gordon.

"2","YORK GALLERIA","2899 WHITEFORD RD SP 17","York","York","PA","17402 0000","US","31",,,,,"717 840 4007","04005",,,,,,,,,,,,,,,,,,,,,,,,,,,,,"Gordon",,

3. Uploading & Downloading Store Data

The data for Site Advantage can be uploaded to and downloaded from https://trc.mapquest.com/ .

User name: 32643 (client id)

Password: Zale.Corp

Click “Data Manager” for uploading and downloading the data

3.1 Uploading data

After formatting the store data in the required text format and giving it a .txt extension, the data is loaded into the Data Manager.

To upload the data file, click on Data Manager link in the navigation menu, then click on Upload File link. Browse for the store data file, and click on Upload link. This uploaded data will be processed by MapQuest, after which it will be stored in the staging database. The staging database is for testing and will not be available to the users. After the staging data has been process, MapQuest will send an email. The Zales store data file, which has been uploaded into MapQuest database, has been named MapQuestData_rev1.txt.

To see the errors in the data, click on Data Summary link. If required, the data can be edited using the Data Summary page or the data file can be edited offline and loaded back into MapQuest. When the edited data is loaded into MapQuest, the original data is replaced with the edited data.

To actually use the data as production data, the staging data must be moved to the MapQuest production database. Click on Production link in the navigation menu to push data into production. After the data has been pushed to production, MapQuest will send an email. Refer to chapter 8 of the MapQuest Data Manager user guide for details.

3.2  Downloading Data

To get a printout of the errors in the data, go to https://trc.mapquest.com/, click the Download Data link, and then click on Errors link. An excel file in csv format will be downloaded. The records in this file have not been downloaded due to some problem in the record, like non-unique recordid, or missing data. These records need to be corrected.

To get a printout of the Ambiguities in the data, go to https://trc.mapquest.com/, click the Download Data link, and then click on Ambiguities link. These records have not been downloaded due to some problem in the address which produced multiple matches. The Ambiguities file downloaded from MapQuest is named 32643_ambig.csv. This file contains 176 records which have not been uploaded to MapQuest server. These records need to be corrected.

To get a printout of the processed data, go to https://trc.mapquest.com/, click the Download Data link, and then click on Staging Data link. These are the records which have been processed for errors.

To get a printout of the production data, go to https://trc.mapquest.com/, click the Download Data link, and then click on Production Data link. These are the records which have been pushed to production.

When the staging or production data is downloaded, look at the Geocode Quality column. Geocoding is the process which assigns a latitude and longitude coordinate to the location. The values in Geocode Quality column are populated automatically when the data is processed by Mapquest, and can be used to improve the quality of the address.

The values of Geocode Quality column were checked for different records and following conclusions were drawn:

Address This is the highest geocode quality.

Intersection There is some problem in the intersection.

Street There is some problem in Street.

Zip9 Last four digits required in Zip, otherwise their can

be multiple matches.

Zip7 Could not find the address; will give a map of the city only.

4.  Location of the software and directories

The software has been loaded in a PC with IP address 197.1.25.79. All the files mentioned are in the SiteAdvantage folder.

Directory Contents

C:\Mapquest / This directory contains the documentation and software downloaded from MapQuest technical resource site.
C:\SiteAdvantage / C-Sharp, ASP.net, Config and resource files
C:\SiteAdvantage\xslt / Files with xsl and css extension.
C:\SiteAdvantage\images / Image files
C:\SiteAdvantage\StoreData_SA / Zales store data uploaded into MapQuest for SiteAdvantage service.
File: c:\mapquest\storedata_sa\MapQuestData_rev1.txt.
C:\SiteAdvantage\StoreData_SA\StoreData_SA / This folder contains files downloaded from MapQuest.
C:\SiteAdvantage\StoreData / Store data used to create MapQuestData_rev1.txt
Data files changed to new format(zalebrands.mdb)
C:\SiteAdvantage\documentation / MapQuest documentation

5. How the MapQuest Software works

1  The first step is to enter a query string in the address bar of Internet Explorer. Query string includes a parameter named “Brand”. For example to view Zales Jeweler stores near an address, value of this parameter will be “Zales”. To view stores that carry a particular designer products in the Bailey Banks and Biddle stores, another parameter named “Designer” is to be given, with the value “yes”. The query string for different brands is given below. Wherever localhost is specified in the query string, replace it with the name of the actual server on which the application is deployed.

a)  For store locator function of the Zales Brand:

Http://localhost/SiteAdvantage/SiteAdvantage,aspx?Brand=Zales.

b)  For the store locator function of the Bailey Banks and Biddle Brand:

Http://localhost/SiteAdvantage/SiteAdvantage.aspx?Brand=Bailey

c)  For the store locator function for Bailey Banks and Biddle Brand which carry a particular designer products:

Http://localhost/SiteAdvantage/SiteAdvantage.aspx?Brand=Bailey&Designer=yes

d)  For the store locator function of the Gordon Brand:

Http://localhost/SiteAdvantage/SiteAdvantage.aspx?Brand=Gordon

e)  For store locator function of the Zales Outlet:

Http://localhost/SiteAdvantage/SiteAdvantage,aspx?Brand=Outlet.

f)  For store locator function of the Mappins Brand:

Http://localhost/SiteAdvantage/SiteAdvantage,aspx?Brand=Mappins.

g)  For store locator function of the Peoples Brand:

Http://localhost/SiteAdvantage/SiteAdvantage,aspx?Brand=Peoples

h)  For store locator function of the Piercing Pagoda Brand:

Http://localhost/SiteAdvantage/SiteAdvantage,aspx?Brand=Pagoda.

2  When the query string is submitted, Advantage.aspx.cs file (which is in the SiteAdvantage folder) is executed. A form is displayed, asking the user to enter the address near which the stores are to be found. The display screen will be different for different brands. After the user enters the address and submits, address parameters are added to Brand and Designer parameters which were initially given by the user.

3  The control passes back to Advantage.aspx.cs. A function generate() function is called and the parameters are collected in a lParams object, which is a NameValueCollection object. BuildURL() method is called, which returns a URL based on these parameters. A HttpWebRequest object is created by executing Create() method of WebRequest class, and passing this URL as an argument. Proxy parameters are added to HttpWebRequest object. In the proxy object, credential parameters are passed to submit to the proxy server for authentication. If the username and password in the credential parameters are changed, the code has to be rebuilt Whenever the software is executed from any Zales client PC, these proxy parameters are required. When the software is loaded on the server, these lines have to be removed. Specifically, the lines in which a proxy object is created, Credential property is set, and this proxy object is attached the to HttpWebRequest object have to be removed. This is mentioned as a comment in the source code.

4  An HttpWebResponse object is created by calling GetResponse() method on HttpWebRequest. object. The response is stored in result string. This string is passed as an argument in LoadXML method of XML document object.

5  A class variable, named lstemplate is declared in Advantage.aspx.cs. The variable is given a value map_search.xsl. An XslTransform object is created, Load() method is called with the lstemplate variable as its argument. XsltArgumentList object is created, and some parameters like formUrl are attached to this object. formUrl contains the virtual path of the script name. This is obtained from the URL which was built in the third step. Virtual path is the path in the URL which follows the server name.

Transform() method is called on XslTransform object , with XML document object and XsltArgument objects as arguments. This method load and runs the map_search.xsl stylesheet.

<xsl:include> element includes the contents of one style sheet into another. Following stylessheets are included in map_search.xsl:

Page_elements.xsl

Map_search_logic.xsl

Map_common.xsl

Map_search_query.xsl

Map_search_results.xsl

Links to cascading stylesheets for different brands are included in map_search.xsl file. All these cascading stylesheets are in the image sub folder of siteAdvantage folder.

Brand / Stylesheet name
Zales Jewelers / styleZales.css
Bailey Banks and Biddle / styleBailey.css
Bailey Banks and Biddle for designers / styleDesigner.css
Gordon / styleGordon.css
Piercing Pagoda / stylePagoda.css
Mappins / styleMappins.css
Peoples / stylePeoples.css
Zales Outlet / styleOutlet.css

These stylesheets can be changed to change the presentation of the result.

Map_search.xsl also calls the header template of page_elements.xsl. In this header template, brand logo have been called. The logo files, which are GIF files, are in the image sub folder of siteAdvantage folder.

Brand / File name for Logo
Zales Jewelers / Zaleslogo.gif
Bailey Banks and Biddle / Baileylogo.gif
Bailey Banks and Biddle for designers / Baileylogo.gif
Gordon / Gordonslogo.gif
Mappins / MappinsLogo.gif
Peoples / PeoplesLogo.gif
Zales Outlet / OutletLogo.gif

If the logo is to be changed, simply replace these files with corresponding new files. Copy the logo of Piercing Pagoda into the image sub folder, change the source code of page_elements.xsl as per the comments,

Template map_logic, which is in map_search_logic.xsl file, is then called. No change has been made in map_search_logic.xsl. After the URL is submitted to MapQuest, based on the error codes returned, either query template (in map_search_query) or results template (in map_search_results) is called. If the query template is called, a form is displayed where the user can enter the address near which stores are to be found. If results template is called, MapQuest returns the nearby stores and their maps. If the user presses the driving direction button, route_search_results is called to display the driving directions.

6.  Files modified for customization of SiteAdvantage:

1  File C:\SiteAdvantage\Advantage.aspx.cs :

i.  Modified to take care of Zale Proxy.

ii.  Three parameters were added:

a.  vfirstCount - This parameter was added to find out whether page is loaded the first time. This was used to prevent the error display when page is loaded first time

b.  vtext1- This was used to get the value of text1, which is the brand name. text1 is a parameter in the query string which goes to mapquest for display of maps.

c.  vDesigner- vDesigner is the variable used to get the value of designer parameter from the query string. This is used to find out whether we want to find out the Bailey Banks and Biddle stores that carry products of a particular designer.

After getting/setting the values, these variable are then added to XslArgumentList Object. For details, see the section 5 - “How the MapQuest software works”.

2  File C:\SiteAdvantage\xslt\map_search.xsl :

i.  Modified to get different stylesheets for different brands. The stylesheet is selected based on brand, and whether it is a designer product (only for. Bailey Banks and Biddle brand).

ii.  Parameter pTemplate added. This was used to change the screen layout for Bailey banks and Biddle designer stores when MapQuest was not able to find the driving directions due to some problem in the store address.