Профессиональный пакет API Карт Google
Те же замечательные карты плюс SLA, поддержка и контроль рекламы
Добро пожаловать на страницу документации API Карт Google для разработчиков! С помощью API Карт Google на основе JavaScript вы сможете встроить Карты Google в свои веб-страницы. Для использования API прежде всего нужно зарегистрироваться для получения ключа API. Получив ключ API, можно разрабатывать приложение для карт, следуя советам в этой документации.
Новинка! Познакомьтесь с версией 3 API Карт, недавно выложенной нами в Лаборатории Google!
Новинка! Используйте AdSense для Карт в своих приложениях API Карт!
Данная документация предназначена для пользователей, знакомых с программированием на основе JavaScript и принципами объектно-ориентированного программирования. Также требуется знание основ работы пользователя с Картами Google. В Интернете можно найти множество руководств по JavaScript.
Эта документация, не является полной и исчерпывающей, она сделана для того, чтобы вы могли быстро начать изучение и разработку интересных приложений, используя API Карт Google. Мы также публикуем справочные материалы по API Карт Google, содержащие относительно полную информацию.
Недавно мы изменили структуру документации, добавив дополнительные сведения и разделив рассматриваемые вопросы на следующие ключевые области:
Надеемся, что новая структура будет удобнее, особенно для разработчиков, только начинающих работать с API Карт. Ждем отзывов о документации. Не забудьте присоединиться к форуму API Карт для разработчиков, где можно оставить отзыв и обсудить этот API.
API карт Google теперь поддерживает маплеты (карты плюс гаджеты), которые позволяют встраивать внешние приложения в Карты Google. Эти маплеты работают в собственных iFrames, это позволяет, например, создавать "мэшапы мэшапов" и смешивать коды с разных сайтов. Это открывает целый мир новых возможностей программирования с Картами Google! Писать маплеты легко, хотя некоторые вещи делаются иначе, чем в обычном API Карт Google. Для получения дополнительных сведений обратитесь к документации по маплетам Карт Google и справочным материалам.
Теперь API Карт Google полностью интегрирован с AJAX API Google. Эта среда позволяет загружать один ключ API для всех поддерживаемых API Google AJAX (в том числе Карт Google), а также предоставляет для всех API общее пространство имен, обеспечивая совместную работу разных API Google. Не беспокойтесь, если вы не хотите использовать среду API Google AJAX, можно продолжать использовать существующее пространство имен.
Использовать среду API Google AJAX относительно просто. Для того, чтобы приложение могло использовать среду, нужно изменить его следующим образом.
| 
http://maps.google.com/apis, загрузите общий загрузчик с http://www.google.com/jsapi. Передать свой ключ API Карт Google можно на этот URL:
<script type="text/javascript" src="http://www.google.com/jsapi?key=ABCDEFG"></script>
google.load. Метод google.load принимает аргумент для конкретных API и номера версии, которые нужно загрузить:
<script type="text/javascript">
google.load("maps", "2");
</script>
google.maps.* для всех классов, методов и свойств, которые вы используете в API Карт Google, заменив префикс G этим пространством имен. Выполните инициализацию объектов с помощью google.setOnLoadCallback(). Например, объект GMap2 соответствует google.maps.Map2 при использовании загрузчика API Google AJAX:
<script type="text/javascript" src="http://www.google.com/jsapi?key=ABCDEFG"></script>
<script type="text/javascript">
google.load("maps", "2.x");
// Call this function when the page has been loaded
function initialize() {
var map = new google.maps.Map2(document.getElementById("map"));
map.setCenter(new google.maps.LatLng(37.4419, -122.1419), 13);
}
google.setOnLoadCallback(initialize);
</script>
Полную версию документации по использованию загрузчика API Google AJAX можно найти на странице http://code.google.com/apis/ajax/documentation/.
API Карт Google использует параметр предпочитаемого языка браузера при отображении текстовой информации, такой как имена элементов управления, уведомления об авторском праве и маршруты поездок. Если вы хотите изменить API Карт, чтобы он игнорировал этот параметр браузера и отображал информацию на определенном языке, то можно добавить дополнительный параметр hl к тегу <script>, включая код JavaScript API Карт, указав язык домена, который следует использовать.
Например, для отображения приложения на API Карт на немецком, добавьте к тегу <script> &hl=de, как показано ниже:
<script type="text/javascript" src="http://maps.google.com/maps?file=api&v=2&key=abcdefg&hl=de"
Просмотрите также список поддерживаемых доменных языков. Обратите внимание на то, что мы регулярно добавляем языки, поэтому этот список может быть неполным.
Языки с двунаправленным письмом (такие как арабский и иврит) требуют особого внимания. Эти языки сказываются на компоновке информационных окон и других элементах пользовательского интерфейса API Карт. Как следствие, API Карт будет применять эти языки только если они установлены прямо, через соответствующий параметр hl, или если в API Карт загружен параметр allow_bidi=true и настройки браузера пользователя указывают язык с двунаправленным письмом. Отметьте, что настройки браузера сами по себе не могут вызвать изменения языка.
<script type="text/javascript" src="http://maps.google.com/maps?file=api&v=2&key=abcdefg&allow_bidi=true"
API Карт Google предоставляет пространство имен только для чтения GLanguage, которое можно использовать для запроса языковых параметров, используемых приложением API Карт. В частности, GLanguage.getLanguageCode() возвращает код языка BCP 47, используемый приложением, тогда как GLanguage.isRtl() запрашивает, использует ли язык двунаправленное письмо.
(Дополнительные сведения приведены в GLanguage справочной документации.)
Использование API Карт Google теперь требует указать, использует ли ваше приложение датчик (такой как локатор GPS) для определения местонахождения пользователя. Это особенно важно для мобильных устройств. Приложения должны передавать требуемый параметр sensor тегу <script> при включении в себя кода JavaScript API Карт, указывающего, использует ли приложение устройство датчика.
Приложения определяющие местоположение пользователя посредством датчика должны передавать &sensor=true при загрузке API Карт JavaScript, через http://maps.google.com/maps, либо с помощью обычного загрузчика.
#
# Example using sensor when loading the Maps JavaScript API
#
<script type="text/javascript" src="http://maps.google.com/maps?file=api&v=2&key=abcdefg&sensor=true">
#
# Example using sensor when loading the Maps API via the common loader
#
<script type="text/javascript" src="http://www.google.com/jsapi?key=abcdef"></script>
<script type="text/javascript">
google.load("maps", "2",{"other_params":"sensor=true"});
function initialize() {
var map = new google.maps.Map2(document.getElementById("map"));
map.setCenter(new google.maps.LatLng(37.4419, -122.1419), 13);
}
google.setOnLoadCallback(initialize);
</script>
Обратите внимание, что даже если датчик не используется, этот параметр все равно следует передать, установив его значение на false.
Прежде, чем погрузиться в API Карт Google, следует обратить внимание на следующее, чтобы ваше приложение надежно работало во всех платформах, на которые оно рассчитано.
API Карт Google поддерживает те же браузеры, что и веб-сайт Карт Google. Синтаксический анализ скрипта http://maps.google.com/maps?file=api&v=2 выполняется безошибочно практически в любом браузере, поэтому его можно безопасно включать перед проверкой совместимости.
Различные приложения иногда нуждаются в разном поведении для пользователей, имеющих несовместимые браузеры. API Карт предоставляет глобальный метод (GBrowserIsCompatible()) для проверки совместимости, но не имеет автоматического поведения при обнаружении несовместимого браузера. Большинство примеров в этом документе не проверяют совместимость с браузером и не отображают для старых браузеров сообщение об ошибке. Настоящие приложения должны как-то вежливее поступать с несовместимыми браузерами, но мы опустили эти проверки, чтобы примеры были более удобочитаемы.
Приложения, кроме простейших, неизбежно столкнутся с несовместимостью с браузерами и платформами. Для этих проблем нет простых решений, но с помощью таких ресурсов, как форум разработчиков API Карт Google и quirksmode.org, можно найти обходные пути.
API Карт Google по умолчанию, выдает результаты и предоставляет текстовые элементы, используя кодировку символов UTF-8. Как правило, ее использование предпочтительно. Однако, если ваша страница HTML закодирована с использованием другой схемы кодировки, это может вызвать проблемы. В этих случаях необходимо гарантировать использование одинаковой схемы кодировки страницей HTML и API Карт Google.
Схему кодировки страницы HTML можно установить, установив параметр content:charset в теге <meta>:
<meta http-equiv="content-type" content="text/html; charset=utf-8"/>
Если ваше веб-приложение поддерживает UTF-8, установите тег <meta>, как показано выше. Все примеры в документации для API Карт используют эту схему кодировки.
В некоторых случаях веб-страница может использовать (или должна использовать) отличающуюся кодировку символов. В этих случаях кодировку результатов, выводимых API Карт, можно установить используя параметр oe при первой загрузке API Карт с тегом <script>. Параметр oe поддерживает множество кодировок, наиболее популярные их которых отмечены ниже:
utf-8 или utf8 –·кодировка UTF-8 (установлена по умолчанию).iso-8859-1 или latin1 – западноевропейская кодировка ISO-8859-1.iso-8859-2 или latin2 – восточноевропейская кодировка ISO-8859-2.iso-8859-5 или cyrillic – русская (кириллица).iso-8859-7 или greek – греческая.iso-8859-8 или hebrew – иврит.shift_jis – японская.gb2312 – упрощенная китайская.big5 – традиционная китайская.Помните, что настоятельно рекомендуется использовать кодировку по умолчанию oe=utf-8. Иную кодировку следует устанавливать только при наличии страницы HTML, не поддерживающей UTF-8.
Дополнительные сведения о схемах кодировки можно найти в статье Кодировка символов.
Мы советуем использовать совместимый со стандартами XHTML на страницах, содержащих карты. Если браузер видит наверху страницы XHTML DOCTYPE, он выводит страницу в "режиме совместимости со стандартами", позволяя гораздо надежнее предсказывать отображение и поведение в разных браузерах. Страницы без такого определения типа могут быть обработанными в "режиме обратной совместимости", что часто приводит к несогласованности макета.
Если вы хотите показывать на своей карте ломаные линии (как линии, которыми на Картах Google обозначаются маршруты поездок), следует включить пространство имен VML в свой документ XHTML, чтобы все правильно работало в Internet Explorer. Начало документа XHTML должно выглядеть так:
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xmlns:v="urn:schemas-microsoft-com:vml">
Параметр v в URL http://maps.google.com/maps?file=api&v=2 относится к нужному номеру версии API Карт Google. Большинство пользователей API используют текущую "версию 2" API, передавая в этом URL параметр v=2. Вместо этого, можно получить последний выпуск (включающий самые новые функции), передав v=2.x. Но имейте в виду, что последний выпуск может быть менее надежен, чем v=2. Мы регулярно обновляем API Карт Google (иногда каждую неделю). В эти моменты функции в выпуске v=2.x переносятся в выпуск v=2, если не обнаружено проблем.
Кроме того, можно использовать "стабильную" версию API, передавая параметр v=2.s. Эта версия обновляется реже, примерно раз в несколько месяцев. Так как выпуски v=2 и v=2.x обновляются примерно раз в две недели, некоторые разработчики могут предпочесть использовать стабильный v=2.s. Заметьте, что стабильная версия может быть на несколько версий старше текущей и не включать некоторых новейших функций.
Каждая версия API при обновлении получает отметку (например, "версия 2.76"). При обновлении API старый код, основанный на предыдущих версиях, может иногда работать не полноценно. Если вам совершенно необходимо привязать приложение в определенному выпуску API, это можно сделать, явно включив версию в параметр v (например, v=2.75). Это, однако, не рекомендуется. Всегда лучше основывать продукты на коде по мере его обновления.
Внося значительные изменения в API, мы увеличиваем главный номер версии и размещаем уведомление на Google Code и нафоруме по API Карт для разработчиков. При этом мы будем поддерживать обе версии не меньше месяца, чтобы вы могли перевести свой код.
Команда Карт иногда явно обновляет API, исправляя недавно обнаруженные ошибки и улучшая производительность. Эти обновления должны только улучшать производительность и исправлять ошибки, но мы можем случайно нарушить работу некоторых клиентов API. Пожалуйста, сообщайте о таких проблемах на форуме по API Карт для разработчиков.
В этой документации речь идет о версии 2 API Карт, выпущенной 3 апреля 2006. Если ваш API использует версию 1 API Карт (то есть вы разрабатывали сайт до 3 апреля 2006), следует попробовать обновить веб-сайт. Дополнительные сведения приведены в Руководстве по обновлению до версии 2.
Заметьте, что большинство примеров в этой документации показывают только рассматриваемый код JavaScript, а не весь файл HTML. Код JavaScript можно вставить в файл-остов HTML, либо вы можете скачать полный файл HTML для каждого примера, нажав ссылку после примера.
API Карт Google поддерживает использование замыканий функций, а класс GEvent системы обработки событий API связывает события с DOM-узлами таким образом, что это почти неминуемо приводит к утечкам памяти в некоторых браузерах, особенно в Internet Explorer. Версия 2 API Карт включает новый метод, GUnload(), который удаляет большинство циклических ссылок, приводящих к таким утечкам. Следует вызывать GUnload() в событии onunload своей страницы, чтобы уменьшить вероятность утечки памяти в вашем приложении:
<body onunload="GUnload()">
Использование этой функции практически исключило утечки памяти в Internet Explorer в Картах Google, но следует, тем не менее, если есть проблемы с потреблением памяти, проверять утечки памяти на своем сайте с помощью таких средств, как Drip.
Вот несколько дополнительных ресурсов. Заметьте, что эти сайты не поддерживаются и не принадлежат Google.
Вот несколько подходов, которые могут помочь, если код не работает: