embed

チュートリアル Step 0: 地図を表示する

embed は、Geolonia Maps の中で記述量が最も少ないライブラリです。この Step では、HTML ファイルを1つ作成し、ブラウザに地図を表示します。

地図を表示する

必要なファイルは HTML 1つだけです。次の内容を index.html という名前で保存してください。

<!doctype html>
<html>
  <head>
    <meta charset="UTF-8">
    <title>embed</title>
    <style>
      .geolonia { width: 100%; height: 400px; }
    </style>
  </head>
  <body>
    <div class="geolonia"></div>
    <script src="https://cdn.geolonia.com/embed/v5/embed?geolonia-api-key=YOUR-API-KEY"></script>
  </body>
</html>

上に書いた index.html が、そのまま下で動作しています。

地図が表示される仕組みは次の2点です。

class="geolonia" を持つ div：ここが地図になります。div 自体には大きさがないので、CSS で高さを与えています（高さが 0 だと地図は見えません）。
CDN の <script>：読み込まれると、ページ内の .geolonia 要素を探して地図に変えます。URL の YOUR-API-KEY はお試し用のデモキーで、localhost や GitHub Pages・CodePen などの開発・プレビュー環境で地図が描画されます（動く環境の一覧。自分のキーの発行は Step 5 で扱います）。

ブラウザで開く

保存した index.html をダブルクリックで開いても、地図は表示されません。デモキーは許可された環境からのアクセスでしか描画されず、ファイルを直接開いた状態（file://）はその対象外だからです。

手軽なのは、index.html を置いたフォルダで簡易ローカルサーバーを起動して、localhost として開く方法です。次のうち、手元で使えるものを使ってください。

# Node.js があるなら
npx serve

# Python があるなら
python3 -m http.server

# Windows で Python があるなら
py -m http.server

npx serve は起動時に URL を表示するのでそれを開きます。http.server の場合は http://localhost:8000/ を開きます。

すでに HTML を置いて公開している Web サーバーがあるなら、そこに index.html をアップロードしても構いません。ただしデモキーが動くのは許可された環境だけなので、その場合は Step 5: API キーの設定と本番公開に先に進み、自分のキーを発行して差し替えてください。

サーバーを用意せずに試したい場合は、CodePen や JSFiddle などのオンラインエディタに貼り付けても地図が出ます。ほかにどんな環境で動くかはデモキーで無料で試せる環境にまとめてあります。

動いたか確認する

場所を何も指定していないので、地図は世界全体が見える状態で表示されます。マウスのドラッグで動き、ホイールで拡大縮小できれば成功です。

うまく出ないとき

真っ白で何も出ない → .geolonia の高さが 0 になっていないか。<style> の指定を確認。
「地図が表示できません」のような表示 → デモキーが効かない環境で開いています。ファイルを直接（file://）開いていないか確認し、上の「ブラウザで開く」の方法で開き直してください。
何も起きない → <script> の URL のつづりを確認。ネットワークがオフラインでも出ません。

書ける属性の一覧

地図の場所や見た目は、div に data-* 属性を追加して指定します。以降の Step で必要なものを順に使うため、この時点ですべてを把握する必要はありません。

書ける属性の全一覧と既定値は、リファレンスの EmbedAttributes にまとまっています。「こんな指定はできるのだろうか」と思ったときに開いてください。

次の Step

以上で、HTML ファイル1つによる地図の表示は完了です。次の Step 1: 初期位置とズームの設定で、地図の中心座標、拡大率、傾きを指定します。