Five Secrets of Ayna Maps

Five Secrets of Ayna Maps
Adonis El Fakih, CEO, Ayna Corporation

With the recent launch of Ayna maps , covering 26 major cities in 17 Arabic countries, web developers and geo enthusiasts can finally take advantage of the street level detail to build geo-enabled tools to promote local business.

In this article I will uncover many unknown Ayna map secrets that will help developers build amazing web applications that take full advantage of what Ayna has to offer. Before we start, it is important to note that Ayna utilizes many Open Source projects and in turn its services supports many open source APIs, making developing tools to talk to Ayna services possible with little effort.

Geographically speaking Ayna maps use EPSG:4326 projection, also known as WGS84, and according to Wikipedia.org the “EPSG:4326 is a common coordinate reference system that refers to WGS84 as (latitude, longitude) pair coordinates in degrees with Greenwich as the central meridian. Any degree representation (e.g. decimal or DMSH: degrees minutes seconds hemisphere) may be used. Which degree representation is used must be declared for the user by the supplier of data.”. This projection is slightly different from Mercator projection used by Google maps, and those differences are apparent when you look at some countries, however it does not affect the overall experience of the maps, navigation, or functionality.

Ayna uses OpenLayers to display its maps. OpenLayers is completely free, Open Source JavaScript, released under a BSD-style License, and according to the developers the software can display map tiles and markers loaded from any source. OpenLayers was initially developed by MetaCarta, which gave it to the public to further the use of geographic information of all kinds.  

Ay first glance, the JavaScript used on Ayna maps is somewhat difficult to understand, and this is where I will start by sharing the first secret about a much simpler interface to the maps available on map961.ayna.com which demonstrates how to display an Ayna map layer with OpenLayers see Figure 1.  The map displayed shows a tiled vector map of the Middle East and North Africa (more about this later in this article).  You can also observe in Figure 1 that two layers are available “tile:EN:2t” and “tile:AR:2t” which stand for the English and Arabic tiles layers. The 2T term is an internal reference to Ayna to track the version of map posted online.

Secret #1  OpenLayers map interface available on map961.ayna.com


Figure 1. map961.ayna.com OpenLayers map interface

By looking into the source code available on that page, we can see how OpenLayers is used to define the two layers, tiles_en2t, and tiles_ar2t.

var tiles_en2t = new OpenLayers.Layer.KaMap( "tile:EN:2t",
        "http://map961.ayna.com/tiles",
        { g: "__base__",i: "png", map: "2t_en"},
        { ratio: 1,transparent: false, isBaseLayer: true}
            );
tiles_en2t.addOptions({ratio:1});

var tiles_ar2t = new OpenLayers.Layer.KaMap( "tile:AR:2t",
            "http://map961.ayna.com/tiles",
        { g: "__base__",i: "png",map: "2t_ar"},
        { ratio: 1,transparent: false, isBaseLayer: true}
            );
        tiles_ar2t.addOptions({ratio:1});

It is important to note that the map961.ayna.com site is not the main map site, and that it will change with time, but at least it is a good place to see how things work and to learn from the examples provided therein.
Previously I used the term tiled vector map, by which I introduce you to the second secret.  Typically geographic map servers produce maps on demand, however the process is very slow, especially when it is used in an online environment.  Google and Ayna use tiling techniques to speed up the serving of maps by pre-creating maps for all the zoom levels covered by a given map provider.  There are many standards for creation and serving tiles, and Ayna uses the KaMap tiling style, which is supported by OpenLayers.

Secret #2 Ayna uses KaMap tiling standard

Ayna map coverage is restricted to the following scale levels and areas starting from street level mapping at 1:3000 scale to 1:3 million covering the entire Middle East and North Africa and starting 1: 5 million to 1:500 million scale encompasses the entire globe.

Using OpenLayers built-in KaMap you can call the current public map “2t”  using the following syntax:

        var tiles_en2t = new OpenLayers.Layer.KaMap ("tile:EN:2t",
                        "http://map961.ayna.com/tiles",
                {
                  g: "__base__",
                  i: "png",
                  map: "2t_en"
                }
             

where the tiles are being served from the /tiles path on Ayna’s map server, the layer name os called __base__, and it is in png format, and your choice of maps the 2t_en (English) or 2t_ar (Arabic).

Ok so at this stage, you know what tools to use to build an application that can show maps from Ayna, what are the layers available, and what is the coverage. So what can we really do with this map?

Well there are many options available to you the minute you start using OpenLayers, for instance you can overlay your own information on top of Ayna maps, using KML, CSV, GeoRSS to mention a few.

In this article I will share with a GeoRSS example, and will includes other types of data in future articles. Ayna tags most news with a latitude and longitude representing the coordinates of the most prominent location mentioned in the article. These coordinates are available in the search results in GeoRSS format.  

The GeoRSS enabled RSS feed is available at http://www.ayna.com/search.en.php?q=ayna:news&rss=1&h=20&c=n where:

q: is the search query. Ayna has a special query called ayna:news which retrieves the latest news. A developer can replace the default query with any search query.
rss: prompts the search engine to output in RSS format.  The valid value is 1
h: is the number of results to retrieve, and in this example 20 are being requested.
c: is the name of the news collection, which is the only Ayna collection that has Geo referenced results.

Note: As of writing of this article the beta GeoRSS feed is only available for English news available from search.en.php, future versions will include support for Arabic and French at search.ar.php and search.fr.php respectively.

To display Ayna’s GeoRSS enabled news, we resort again to OpenLayers support for GeoRSS by defining a map object, a KaMap map layer, a “red” icon which will be used to mark the news location, a GeoRSS object

        map = new OpenLayers.Map('map', {
            scales: [3000, 6000, 10000, 15000, 25000, 50000, 100000,
            250000, 500000, 1000000, 3000000, 5000000, 10000000,
            15000000, 25000000, 35000000
        ],
        controls: []
        });

var tiles_en2t = new OpenLayers.Layer.KaMap( "tile:EN:2t",
        "http://map961.ayna.com/tiles",
        { g: "__base__",i: "png", map: "2t_en"},
        { ratio: 1,transparent: false, isBaseLayer: true}
            );
tiles_en2t.addOptions({ratio:1});

var red = new OpenLayers.Icon("http://www.ayna.com/images/maps/icons/red-dot.png",
new OpenLayers.Size(22,22),
new OpenLayers.Pixel(-11,-23));
        
var layer_options = {};
layer_options.maxResolution = 500;
layer_options.useFeedTitle = true;
layer_options.icon=red;
    layer_options.popupSize = new OpenLayers.Size(400,100);
layer_options.panMapIfOutOfView = true;
var geoRSS = new OpenLayers.Layer.GeoRSS( 'GeoRSS', 'http://www.ayna.com/search.en.php?q=ayna:news&c=n&rss=1&h=100', layer_options);
map.addLayer(geoRSS);

map.addLayers([tiles_en2t]);
map.addControl(new OpenLayers.Control.LayerSwitcher());
map.addControl(new OpenLayers.Control.MouseToolbar());
map.addControl(new OpenLayers.Control.MousePosition());
map.addControl(new OpenLayers.Control.PanZoomBar());
map.addControl(new OpenLayers.Control.Scale());

Figure 2 shows the output of the code included herein. Red icons mark the location of the news and by clicking on them an excerpt of the news is displayed in the popup window.

Secret #3  Display GeoRSS feeds on top of Ayna maps with OpenLayers



Figure 2.GeoRSS feed displayed on top of Ayna Maps

Figure 3. Adding Adonis Rent-A-Car business on ayna maps.

In Figure 3 we can see information of a car rental agency wants to do two things 1) let prospective car buyers find the agency when searching for rental cars in Lebanon, and 2) make is easier for these customers to find the physical location of the agency, by posting the map on their “contact us” page.  

1. Start by zooming quickly to the location of the dealership on the map by holding the control button and selecting with mouse a box area on the map.  After releasing the mouse button, we are zoomed to the extents of the box. Stop at the 1:6000 scale, since it shows the nearby highway and general area.

2. Right click the mouse to show the “add a location” menu.  The popup box is fairly easy, I enter the name of the business, the address as the business prints on business cards, phone, URL and email. (In the new version of Ayna maps, business can add pictures of the store)

3. Click “Add” to submit the information.

4. A small text area is displayed containing HTML code which contains a unique key identifying the newly added point to the map, and helps the agency place a custom map on their site (see Figure 4).

Figure 4. Confirmation popup and custom code

5. At this stage we can copy the iframe code displayed in the popup in figure 4, and paste it in the “contact us” page, to show prospective customers the location of the business on the map.