Для того, щоб відвідувачі вашого сайту змогли побачити мапу на вашій сторінці у них повинен бути встановлений Flash Player 9.0.115 та вище, а також вони повинні використовувати наступні браузери:

Opera 9 та вище
FireFox 2 та вище
Internet Explorer 6 та вище
Safari 3 та вище
Google Chrome

Установка

Для того, щоб користуватись API Mapia, достатньо підключити у документ скрипт:

<script src="http://mapia.com.ua/api/0.9.0/mapiaapi.js"></script>

Найпростіший приклад використання API Mapia API

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" 
"http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" style="height:100%;width:100%;margin:0;padding:0;">
    <head>

        <meta http-equiv="Content-Type" content="text/html;charset=utf-8" />
        <title>Mapia API</title>
        <script src="http://mapia.ua/api/0.9.0/mapiaapi.js" type="text/javascript"></script>
        <script>
          var mapia = new Mapia("map");
        </script>

    </head>

    <body style="margin:0;padding:0;height:100%;width:100%;overflow:hidden;">
      <span id="map"></span>
    </body>
</html>

Конструктор

Mapia(elementId, options)

elementId – DomID елемента, який буде замінений на Flash-об'єкт. Флеш-об'єкту будуть встановлені заначення with та height 100%, це означає, що розмір та позиція карти задаються розміром та позицією контейнера, у якому знаходиться elementId. Приклад

options – параметр типу Object з такими атрибутами:

zoom – початковий рівень наближення карти. Число від 6 (далеко) до 18 (близко)
center – точка, у яку буде цетрована карта. Це может бути або об'єкт з атрибутами lat, lon – де lat та lon – це широта та довгота відповідно; або строка з почтовою адресою.
lang – мова, на якій будуть відображатись назви на карті (доступні варіанти "ru" та "ua")
wmode – параметр wmode буде встановлений флеш об'єкту при вставленні у документ

Приклад 1.

var map = new Mapia('mapia', {center:'площадь Победы 1', zoom:15})

Приклад 2.

var map = new Mapia('mapia', {center:{lat:50.45759, lon:30.38898}, zoom:15})

Методи

getCenter

Повертає координати центру карти в об'єкті {lat:... , lon:...}. Цей метод поверне null, якщо карта ще не ініційована.

setCenter(latlonOrString)

Задає координати карти. Як у конструкторі це може бути latlon об'єкт або строчка з адресою.

setCity(cityTitle)

Встановлює місто, у контексті якого буде робитись пошук адрес для встановлення маркера або центрування карти.

getZoom

Повертає зум карти.

setZoom(number)

Задає зум карти. Можливі значення – від 6 до 18.

addMarker(markerId, latlonOrString, popupData)

Встановлює маркер з ідентифікатором markerId у місце, вказане координатами або адресою у другому параметрі. Якщо такий ідентифікатор вже був використаний іншим маркером, маркер не додасться. Об'єкт popupData містить дані, які повинен відображати попап, може містити наступні атрибут:

title – заголовок. Відображається у підказці при наведенні на маркер. (Обов'язкове поле)
icon_url – url іконки маркера. Якщо іконка знаходится не на mapia.ua, то адреса повинна бути вказана повністю, та на сервері, з якого завантажується іконка, повинен бути файл /crossdomain.xml, що дозволяє доступ домену mapia.ua (Обов'язкове поле)
nopopup – true|false. Встановіть true якщо не хочете, щоб відображався попап при клику на маркер.
custom_content – url *.swf файлу, який є Flex-модулем, який буде підгружений та відображений у попапі. Якщо не вказаний, то буде використаний стандартний модуль. Детальніше про створення модулей змусту попапу нижче.

Усі інші поля будуть передані у модуль, що відображає зміст попапу. Для стандартного модуля можна передавати такі поля:

title – Відображається великими літерами.
category_name – Відображається у попапі над заголовком.
logo – url логотипа, картинка 100x100.
address – адреса.
phone – телефон.
url – адрес веб-сайту. Протокол в url повинен бути вказаний обов'язково. Наприклад: http://example.com
note – текст, який відображається у попапі під адресою, телефоном, е-мейлом.
description – текст у попапі.

Увага!

Є 3 розповсюджені помилки при додаванні маркера:

Не вказаний icon_url, або вказаний відносний url, який інтерпретується відносно http://mapia.com.ua/, а не відносно url сторінки, на яку включена карта;
Вказаний не унікальний ідентифікатор маркера;
На сервері, з якого скачується іконка для маркера, не лежить файл crossdomain.xml.
Можливе рішення проблеми: іконки для маркерів розмістити на своєму сервері, та
у корінь покласти файл crossdomain.xml , наприклад, такого змісту:
```
<?xml version="1.0"?>
<cross-domain-policy>

  <site-control permitted-cross-domain-policies="master-only"/>
  <allow-access-from domain="*" />
</cross-domain-policy>
  
```
Приклад завжди можна побачити тут: http://mapia.ua/crossdomain.xml

Це відноситься тільки для іконок маркеру, та не відноситься до логотипів.

removeMarker(markerId)

Видаляє маркер з вказаним ідентифікатором.

Події

На будь-якому екземплярі классу Mapia можна підписатись на події. У обробник подій буде переданий аргумент event, у якому поле target – це екземпляр класу Mapia, та type – подія, зо відбулася. Іншу поля залежать від пожії, що відбулася.

Приклад використання подій

var i = 0;
var mapia = new Mapia('mapia');
mapia.addEventListener('mapClick', function(event){
  event.target.addMarker((i++).toString(), event.loc, {title:i.toString(), icon_url:'http://example.com/icons/'+i.toString()+'.png'})
});

initialized

Відбувається, коли флеш-об'єкт Mapia створений, завантажений, та готовий виконувати команди від API Mapia. Усі методи екземпляру клас Mapia, викликані до цього події, складаються у чергу, та виконуються безпосередньо перед цією подією.

zoomChanged

Відбувається, коли змінено значення zoom. Параметр event містить додаткове zoom

centerChanged

Відбувається, коли змінений центр карти. Параметр event містить додаткове поле center

mapClick

Відбувається, коли користувач клікає мишкою по карті. Параметр event містить додаткове поле loc – точка на карті, у яку клікнув користувач

markerClick

Відбувається, коли користувач клікає на маркер. Параметр event містить додаткові поля:

markerId – ідентификатор маркеру
loc – довгота та широта маркеру (lat, lon)
popupData – дані для опапу маркера

geocodeSuccess-geocodeFailure

Коли у методах setCenter та addMarker використовується строчка замість LatLon об'єкта, то для цієї строчки буде відправлений на сервер пощуковий запит. Якщо адреса знайдена, то відбудеться geocodeSuccess, шнакше – geocodeFailure.

Створення модуля, що відображає зміст попапу

Модуль повинен імплементувати інтерфейс com.mapia.IPopupContent. IPopupContent.swc

Ось цей інтерфейс:

public interface IPopupContent
{
  function get popupData():Object;
  function set popupData(value:Object):void;
}

Приклад простого модуля, якому можна вказати колір фону та колір тексту.

<?xml version="1.0" encoding="utf-8"?>
<mx:Module xmlns:mx="http://www.adobe.com/2006/mxml" layout="absolute" implements="ua.mapia.IPopupContent">
    <mx:Script>

        <![CDATA[
            private var _popupData:Object

            [Bindable]
            public function get popupData():Object
            {
                return _popupData;
            }

            public function set popupData(value:Object):void
            {
                _popupData = value;
            }
        ]]>
    </mx:Script>
    <mx:Box backgroundColor="{popupData.bgColor}">
        <mx:Label text="{popupData.title}" color="{popupData.color}" />
    </mx:Box>
</mx:Module>

Детальніше про те, як створювати та компілювати Flex-модулі можна почитати тут.

Ви можете оптимізувати ваш модуль для використання його тільки у додатку Mapia, вирізавши з нього всі ті компоненти, які вже є в Mapia.swf (розмір модулю може зменшуватися до 30k). Для цього при компіляції використовуйте аргумент -load-externs, з нашим report.xml.

Документація API