JavaScript kullanarak işaretçi içeren bir Google Haritası ekleme

Giriş

Bu eğitimde, HTML, CSS ve JavaScript kullanarak bir web sayfasına işaretçili Google haritası ekleme işlemi gösterilmektedir. Ayrıca harita seçeneklerini nasıl ayarlayacağınızı ve haritaya etiket eklemek için kontrol yuvalarını nasıl kullanacağınızı da gösterir.

Bu eğitimde oluşturacağınız harita aşağıda gösterilmiştir. İşaretçi, Uluru-Kata Tjuta Ulusal Parkı'ndaki Uluru'ya (Ayers Rock olarak da bilinir) yerleştirilmiştir.

Başlarken

Web sayfanızda işaretçi içeren bir Google haritası oluşturmak için üç adım vardır:

1. API anahtarı alma
2. HTML sayfası oluşturma
3. İşaretçi içeren bir harita ekleme

Web tarayıcısı gerekir. Desteklenen tarayıcılar listesinden platformunuza göre Google Chrome (önerilir), Firefox, Safari veya Edge gibi iyi bilinen bir tarayıcı seçin.

1. adım: API anahtarı alın

Bu bölümde, kendi API anahtarınızı kullanarak uygulamanızın Maps JavaScript API'de kimliğini nasıl doğrulayacağınız açıklanmaktadır.

API anahtarı almak için aşağıdaki adımları uygulayın:

1. Google Cloud Console'a gidin.

2. Proje oluşturun veya seçin.

3. API'yi ve ilgili hizmetleri etkinleştirmek için Devam'ı tıklayın.

4. Kimlik bilgileri sayfasında bir API anahtarı alın (ve API anahtarı kısıtlamalarını ayarlayın). Not: Kısıtlanmamış mevcut bir API anahtarınız veya tarayıcı kısıtlamaları olan bir anahtarınız varsa bu anahtarı kullanabilirsiniz.

5. Kota hırsızlığını önlemek ve API anahtarınızın güvenliğini sağlamak için API Anahtarlarını Kullanma başlıklı makaleyi inceleyin.

6. Faturalandırmayı etkinleştirin. Daha fazla bilgi için Kullanım ve Faturalandırma bölümüne bakın.

7. API anahtarını aldıktan sonra "YOUR_API_KEY"i tıklayarak aşağıdaki snippet'e ekleyin. Bootloader komut dosyası etiketini kopyalayıp kendi web sayfanızda kullanmak üzere yapıştırın.

   <script>
     (g=>{var h,a,k,p="The Google Maps JavaScript API",c="google",l="importLibrary",q="__ib__",m=document,b=window;b=b[c]||(b[c]={});var d=b.maps||(b.maps={}),r=new Set,e=new URLSearchParams,u=()=>h||(h=new Promise(async(f,n)=>{await (a=m.createElement("script"));e.set("libraries",[...r]+"");for(k in g)e.set(k.replace(/[A-Z]/g,t=>"_"+t[0].toLowerCase()),g[k]);e.set("callback",c+".maps."+q);a.src=`https://maps.${c}apis.com/maps/api/js?`+e;d[q]=f;a.onerror=()=>h=n(Error(p+" could not load."));a.nonce=m.querySelector("script[nonce]")?.nonce||"";m.head.append(a)}));d[l]?console.warn(p+" only loads once. Ignoring:",g):d[l]=(f,...n)=>r.add(f)&&u().then(()=>d[l](f,...n))})({
       key: "YOUR_API_KEY",
       v: "weekly",
       // Use the 'v' parameter to indicate the version to use (weekly, beta, alpha, etc.).
       // Add other bootstrap parameters as needed, using camel case.
     });
   </script>

2. adım: HTML sayfası oluşturun

Aşağıda, basit bir HTML web sayfasının kodu yer almaktadır:

<!DOCTYPE html>
<!--
 @license
 Copyright 2025 Google LLC. All Rights Reserved.
 SPDX-License-Identifier: Apache-2.0
-->

<html>
  <head>
    <title>Add a Map</title>

    <link rel="stylesheet" type="text/css" href="./style.css" />
    <script type="module" src="./index.js"></script>
    <!-- prettier-ignore -->
    <script>(g=>{var h,a,k,p="The Google Maps JavaScript API",c="google",l="importLibrary",q="__ib__",m=document,b=window;b=b[c]||(b[c]={});var d=b.maps||(b.maps={}),r=new Set,e=new URLSearchParams,u=()=>h||(h=new Promise(async(f,n)=>{await (a=m.createElement("script"));e.set("libraries",[...r]+"");for(k in g)e.set(k.replace(/[A-Z]/g,t=>"_"+t[0].toLowerCase()),g[k]);e.set("callback",c+".maps."+q);a.src=`https://maps.${c}apis.com/maps/api/js?`+e;d[q]=f;a.onerror=()=>h=n(Error(p+" could not load."));a.nonce=m.querySelector("script[nonce]")?.nonce||"";m.head.append(a)}));d[l]?console.warn(p+" only loads once. Ignoring:",g):d[l]=(f,...n)=>r.add(f)&&u().then(()=>d[l](f,...n))})
        ({key: "YOUR_API_KEY", v: "weekly"});</script>
  </head>
  <body>

    <!-- The map, centered at Uluru, Australia. -->
    <gmp-map center="-25.344,131.031" zoom="4" map-id="DEMO_MAP_ID">
    </gmp-map>

  </body>
</html>

Bu, sayfada harita göstermek için gmp-map öğesini kullanan çok basit bir HTML sayfasıdır. Henüz JavaScript kodu eklemediğimiz için harita boş olacaktır.

Kodu anlama

Örnekteki bu aşamada şunlara sahibiz:

• !DOCTYPE html beyanını kullanarak uygulamayı HTML5 olarak beyan etme.
• Maps JavaScript API'yi önyükleyiciyi kullanarak yüklediniz.
• Haritayı barındırmak için bir gmp-map öğesi oluşturuldu.

Uygulamanızı HTML5 olarak beyan etme

Web uygulamanızda doğru bir DOCTYPE bildirmenizi öneririz. Buradaki örneklerde, uygulamalarımızı aşağıda gösterildiği gibi HTML5 DOCTYPE kullanarak HTML5 olarak beyan ettik:

<!DOCTYPE html>

Çoğu güncel tarayıcı, bu DOCTYPE ile tanımlanan içeriği "standartlar modunda" oluşturur. Bu da uygulamanızın tarayıcılar arası uyumluluğunun daha yüksek olması gerektiği anlamına gelir. DOCTYPE, aynı zamanda düzgün bir şekilde düşürülecek şekilde tasarlanmıştır. Bunu anlamayan tarayıcılar, bu öğeyi yoksayar ve içeriklerini görüntülemek için "quirks modu"nu kullanır.

Quirks modunda çalışan bazı CSS'lerin standartlar modunda geçerli olmadığını unutmayın. Özellikle, yüzdeye dayalı tüm boyutlar üst blok öğelerinden devralınmalıdır. Bu üst öğelerden herhangi biri boyut belirtmezse boyutlarının 0 x 0 piksel olduğu varsayılır. Bu nedenle, aşağıdaki style beyanını ekliyoruz:

<style>
  gmp-map {
    height: 100%;
  }
  html, body {
    height: 100%;
    margin: 0;
    padding: 0;
  }
</style>

Maps JavaScript API'yi yükleme

Önyükleyici, Maps JavaScript API'yi yükleme işlemine hazırlar (importLibrary() çağrılana kadar hiçbir kitaplık yüklenmez).

<script>
  (g=>{var h,a,k,p="The Google Maps JavaScript API",c="google",l="importLibrary",q="__ib__",m=document,b=window;b=b[c]||(b[c]={});var d=b.maps||(b.maps={}),r=new Set,e=new URLSearchParams,u=()=>h||(h=new Promise(async(f,n)=>{await (a=m.createElement("script"));e.set("libraries",[...r]+"");for(k in g)e.set(k.replace(/[A-Z]/g,t=>"_"+t[0].toLowerCase()),g[k]);e.set("callback",c+".maps."+q);a.src=`https://maps.${c}apis.com/maps/api/js?`+e;d[q]=f;a.onerror=()=>h=n(Error(p+" could not load."));a.nonce=m.querySelector("script[nonce]")?.nonce||"";m.head.append(a)}));d[l]?console.warn(p+" only loads once. Ignoring:",g):d[l]=(f,...n)=>r.add(f)&&u().then(()=>d[l](f,...n))})({
    key: "YOUR_API_KEY",
    v: "weekly",
    // Use the 'v' parameter to indicate the version to use (weekly, beta, alpha, etc.).
    // Add other bootstrap parameters as needed, using camel case.
  });
</script>

Kendi API anahtarınızı alma talimatları için 3. adım: API anahtarı alma bölümüne bakın.

Eğitimin bu aşamasında, yalnızca biçimlendirilmemiş etiket metnini gösteren boş bir pencere açılır. Bunun nedeni, henüz JavaScript kodu eklememiş olmamızdır.

gmp-map öğesi oluşturun

Haritanın bir web sayfasında gösterilmesi için haritaya yer ayırmamız gerekir. Genellikle bunu bir gmp-map öğesi oluşturarak ve tarayıcının Belge Nesne Modeli'nde (DOM) bu öğeye referans alarak yaparız. Bunu yapmak için div öğesini de kullanabilirsiniz (daha fazla bilgi) ancak gmp-map öğesini kullanmanız önerilir.

Aşağıdaki kod, gmp-map öğesini tanımlar ve center, zoom ve map-id parametrelerini ayarlar.

<gmp-map center="-25.344,131.031" zoom="4" map-id="DEMO_MAP_ID">
</gmp-map>

center ve zoom seçenekleri her zaman zorunludur. Yukarıdaki kodda center özelliği, API'ye haritanın nerede ortalanacağını söyler ve zoom özelliği, haritanın yakınlaştırma seviyesini belirtir. Yakınlaştırma: 0 en düşük yakınlaştırma düzeyidir ve tüm Dünya'yı gösterir. Dünya'yı daha yüksek çözünürlüklerde yakınlaştırmak için yakınlaştırma değerini daha yüksek bir değere ayarlayın.

Yakınlaştırma seviyeleri

Tüm Dünya'nın haritasını tek bir resim olarak sunmak için ya devasa bir harita ya da çok düşük çözünürlüklü küçük bir harita gerekir. Bu nedenle, Google Haritalar ve Maps JavaScript API'deki harita resimleri, harita "karolarına" ve "yakınlaştırma seviyelerine" bölünür. Düşük yakınlaştırma seviyelerinde, küçük bir harita karosu grubu geniş bir alanı kapsar. Daha yüksek yakınlaştırma seviyelerinde ise karolar daha yüksek çözünürlüklüdür ve daha küçük bir alanı kapsar. Aşağıdaki listede, her yakınlaştırma seviyesinde görmeyi bekleyebileceğiniz yaklaşık ayrıntı düzeyi gösterilmektedir:

• 1: Dünya
• 5: Kara parçası veya kıta
• 10: Şehir
• 15: Sokaklar
• 20: Binalar

Aşağıdaki üç resim, Tokyo'nun aynı konumunu 0, 7 ve 18 yakınlaştırma seviyelerinde göstermektedir.

Aşağıdaki kod, gmp-map öğesinin boyutunu ayarlayan CSS'yi açıklar.

/* Set the size of the gmp-map element that contains the map */
gmp-map {
    height: 400px; /* The height is 400 pixels */
    width: 100%; /* The width is the width of the web page */
}

Yukarıdaki kodda style öğesi, gmp-map boyutunu ayarlar. Haritanın görünür olması için genişliği ve yüksekliği 0 pikselden büyük olacak şekilde ayarlayın. Bu durumda, gmp-map 400 piksel yüksekliğe ve web sayfasının genişliği boyunca görüntülenecek şekilde% 100 genişliğe ayarlanır. Yükseklik ve genişlik stillerini her zaman açıkça ayarlamanız önerilir.

Not: Raster haritalar için maksimum boyut sınırı 6144 x 6144 pikseldir.

Yerleşim kontrolü

Haritanıza HTML form kontrolleri eklemek için kontrol yuvalarını kullanabilirsiniz. Yuva, harita üzerinde önceden tanımlanmış bir konumdur. Bir öğe için gereken konumu ayarlamak üzere slot özelliğini kullanın ve öğeleri gmp-map öğesinin içine yerleştirin. Aşağıdaki snippet, haritanın sol üst köşesine HTML etiketi eklemeyi gösterir.

<!-- The map, centered at Uluru, Australia. -->
<gmp-map center="-25.344,131.031" zoom="4" map-id="DEMO_MAP_ID">
  <div id="controls" slot="control-inline-start-block-start">
    <h3>My Google Maps Demo</h3>
  </div>
</gmp-map>

3. adım: JavaScript kodu ekleyin

Bu bölümde, Maps JavaScript API'yi bir web sayfasına nasıl yükleyeceğiniz ve işaretçili bir harita eklemek için API'yi kullanan kendi JavaScript'inizi nasıl yazacağınız gösterilmektedir.

TypeScript

async function init(): Promise<void> {
    // Request the needed libraries.
    const [{ AdvancedMarkerElement }] = await Promise.all([
        google.maps.importLibrary('marker'),
        google.maps.importLibrary('maps'),
    ]);
    // Get the gmp-map element.
    const mapElement = document.querySelector('gmp-map')!;

    // Get the inner map.
    const innerMap = mapElement.innerMap;

    // Set map options.
    innerMap.setOptions({
        mapTypeControl: false,
    });

    // Add a marker positioned at the map center (Uluru).
    new AdvancedMarkerElement({
        map: innerMap,
        position: mapElement.center,
        title: 'Uluru/Ayers Rock',
    });
}
void init();
index.ts

Not: TypeScript ve Google Haritalar'ı kullanmayla ilgili kılavuzu okuyun.

JavaScript

async function init() {
    // Request the needed libraries.
    const [{ AdvancedMarkerElement }] = await Promise.all([
        google.maps.importLibrary('marker'),
        google.maps.importLibrary('maps'),
    ]);
    // Get the gmp-map element.
    const mapElement = document.querySelector('gmp-map');

    // Get the inner map.
    const innerMap = mapElement.innerMap;

    // Set map options.
    innerMap.setOptions({
        mapTypeControl: false,
    });

    // Add a marker positioned at the map center (Uluru).
    new AdvancedMarkerElement({
        map: innerMap,
        position: mapElement.center,
        title: 'Uluru/Ayers Rock',
    });
}
void init();
index.js

Yukarıdaki kod, initMap() çağrıldığında aşağıdaki işlemleri yapar:

• maps ve marker kitaplıklarını yükler.
• DOM'dan harita öğesini alır.
• İç haritada ek harita seçenekleri ayarlar.
• Haritaya bir işaretçi ekler.

Harita nesnesini alma ve seçenekleri ayarlama

innerMap, Map sınıfının bir örneğini temsil eder. Harita seçeneklerini ayarlamak için harita öğesinden innerMap örneğini alın ve setOptions yöntemini çağırın. Aşağıdaki snippet'te, DOM'dan innerMap örneğinin alınması ve ardından setOptions yönteminin çağrılması gösterilmektedir:

// Get the gmp-map element.
const mapElement = document.querySelector(
  "gmp-map"
) as google.maps.MapElement;

// Get the inner map.
const innerMap = mapElement.innerMap;

// Set map options.
innerMap.setOptions({
  mapTypeControl: false,
});

Haritanın yüklenmesini bekleyin.

gmp-map öğesi kullanıldığında harita eşzamansız olarak yüklenir. Bu durum, başlatma sırasında başka istekler (ör. coğrafi konum veya yer ayrıntıları isteği) yapılırsa yarışma durumuna neden olabilir. Kodunuzun yalnızca harita tamamen yüklendikten sonra çalışmasını sağlamak için başlatma işlevinizde burada gösterildiği gibi bir addListenerOnce boşta etkinlik işleyicisi kullanın:

// Do things once the map has loaded.
google.maps.event.addListenerOnce(innerMap, 'idle', () => {
    // Run this code only after the map has loaded.
    console.log("The map is now ready!");
});

Bunu yaptığınızda kodunuz yalnızca harita yüklendikten sonra çalıştırılır. İşleyici, uygulamanın yaşam döngüsü boyunca yalnızca bir kez tetiklenir.

Dahili performans optimizasyonuyla ilgili not:

Maps JavaScript API, sayfa yükleme hızlarını artırmak için etkileşimli içeriğin yüklenmesini, öğe veya kapsayıcı görüntü alanına yaklaşana kadar dahili olarak erteleyebilir. Bu dahili optimizasyonlar, herhangi bir zamanda ve önceden haber verilmeksizin değiştirilebilir. Bu bütçeler, performansı artırmak için tasarlanmıştır ve faturalandırmayı yönetmek için kullanılmamalıdır. Bir öğe görünür olana kadar faturalandırma yapılmamasını sağlamak için uygulama kodunuzda öğenin oluşturulmasını erteleyin.

Eksiksiz örnek kod

Eksiksiz örnek kodun tamamını burada görebilirsiniz:

TypeScript

async function init(): Promise<void> {
    // Request the needed libraries.
    const [{ AdvancedMarkerElement }] = await Promise.all([
        google.maps.importLibrary('marker'),
        google.maps.importLibrary('maps'),
    ]);
    // Get the gmp-map element.
    const mapElement = document.querySelector('gmp-map')!;

    // Get the inner map.
    const innerMap = mapElement.innerMap;

    // Set map options.
    innerMap.setOptions({
        mapTypeControl: false,
    });

    // Add a marker positioned at the map center (Uluru).
    new AdvancedMarkerElement({
        map: innerMap,
        position: mapElement.center,
        title: 'Uluru/Ayers Rock',
    });
}
void init();
index.ts

Not: TypeScript ve Google Haritalar'ı kullanmayla ilgili kılavuzu okuyun.

JavaScript

async function init() {
    // Request the needed libraries.
    const [{ AdvancedMarkerElement }] = await Promise.all([
        google.maps.importLibrary('marker'),
        google.maps.importLibrary('maps'),
    ]);
    // Get the gmp-map element.
    const mapElement = document.querySelector('gmp-map');

    // Get the inner map.
    const innerMap = mapElement.innerMap;

    // Set map options.
    innerMap.setOptions({
        mapTypeControl: false,
    });

    // Add a marker positioned at the map center (Uluru).
    new AdvancedMarkerElement({
        map: innerMap,
        position: mapElement.center,
        title: 'Uluru/Ayers Rock',
    });
}
void init();
index.js

CSS

/*
 * Always set the map height explicitly to define the size of the div element
 * that contains the map.
 */
gmp-map {
    height: 100%;
}

/*
   * Optional: Makes the sample page fill the window.
   */
html,
body {
    height: 100%;
    margin: 0;
    padding: 0;
}
style.css

HTML

<html>
    <head>
        <title>Add a Map</title>

        <link rel="stylesheet" type="text/css" href="./style.css" />
        <script type="module" src="./index.js"></script>
        <script>
            // prettier-ignore
            (g=>{var h,a,k,p="The Google Maps JavaScript API",c="google",l="importLibrary",q="__ib__",m=document,b=window;b=b[c]||(b[c]={});var d=b.maps||(b.maps={}),r=new Set,e=new URLSearchParams,u=()=>h||(h=new Promise(async(f,n)=>{await (a=m.createElement("script"));e.set("libraries",[...r]+"");for(k in g)e.set(k.replace(/[A-Z]/g,t=>"_"+t[0].toLowerCase()),g[k]);e.set("callback",c+".maps."+q);a.src=`https://maps.${c}apis.com/maps/api/js?`+e;d[q]=f;a.onerror=()=>h=n(Error(p+" could not load."));a.nonce=m.querySelector("script[nonce]")?.nonce||"";m.head.append(a)}));d[l]?console.warn(p+" only loads once. Ignoring:",g):d[l]=(f,...n)=>r.add(f)&&u().then(()=>d[l](f,...n))})({
                key: "GOOGLE_MAPS_API_KEY"
            });
        </script>
    </head>
    <body>
        <!-- The map, centered at Uluru, Australia. -->
        <gmp-map center="-25.344,131.031" zoom="4" map-id="DEMO_MAP_ID">
            <div id="controls" slot="control-inline-start-block-start">
                <h3>My Google Maps Demo</h3>
            </div>
        </gmp-map>
    </body>
</html>
index.html

İşaretçiler hakkında daha fazla bilgi:

• İşaretçiyi erişilebilir hale getirme
• Grafik simgeler içeren işaretçiler
• İşaretçi animasyonları

İpuçları ve sorun giderme

• Enlem/boylam koordinatlarını alma veya bir adresi coğrafi koordinatlara dönüştürme hakkında daha fazla bilgi edinin.
• Haritayı özelleştirmek için stil ve özellikler gibi seçenekleri değiştirebilirsiniz. Haritaları özelleştirme hakkında daha fazla bilgi için stil oluşturma ve harita üzerinde çizim yapma ile ilgili kılavuzları okuyun.
• Kodunuzu test edip çalıştırmak, hata raporlarını okumak ve kodunuzla ilgili sorunları çözmek için web tarayıcınızdaki Geliştirici Araçları Konsolu'nu kullanın.
• Chrome'da konsolu açmak için aşağıdaki klavye kısayollarını kullanın:
  Command+Option+J (Mac'te) veya Control+Shift+J (Windows'da).

• Google Haritalar'da bir konumun enlem ve boylam koordinatlarını almak için aşağıdaki adımları uygulayın.

  1. Google Haritalar'ı bir tarayıcıda açın.
  2. Haritada koordinatlarını öğrenmek istediğiniz tam konumu sağ tıklayın.
  3. Menüden enlem ve boylam koordinatlarını seçin.

• Geocoding hizmetini kullanarak bir adresi enlem ve boylam koordinatlarına dönüştürebilirsiniz. Geliştirici kılavuzlarında, Geocoding Service'i kullanmaya başlama hakkında ayrıntılı bilgi verilmektedir.