@geolonia/embed
v5.1.0
Published
Geolonia embed JS API
Keywords
Readme
@geolonia/embed
JS embed API for Geolonia service.
Features
- webGL vector map rendering
- simple configuration
- map lazy rendering
Examples
https://geolonia.github.io/embed/
Usage
Specify .geolonia class for target elements.
<!DOCTYPE html>
<html>
<body>
<div class="geolonia" ...></div>
<script src="https://cdn.geolonia.com/embed/v5/embed?geolonia-api-key=YOUR-API-KEY"></script>
</body>
</html>Or
<!DOCTYPE html>
<html>
<body>
<div class="geolonia" data-key="YOUR-API-KEY" ...></div>
<script src="https://cdn.geolonia.com/embed/v5/embed"></script>
</body>
</html>Using with npm (for React, Next.js, Astro, Fresh, etc.)
For modern web frameworks, use @geolonia/embed/core — a side-effect-free entry point designed for programmatic use.
npm install @geolonia/embedimport { GeoloniaMap, keyring } from "@geolonia/embed/core";
keyring.apiKey = "YOUR-API-KEY";
const map = new GeoloniaMap({
container: "#map",
style: "geolonia/gsi",
center: [139.7671, 35.6812],
zoom: 14,
});Unlike the default @geolonia/embed entry point, /core does not automatically scan the DOM or set window.geolonia. This makes it safe to use in SSR environments and avoids double-initialization issues in frameworks like React, Preact, and Vue.
Using External Styles Without API Key
You can use external style.json URLs without a Geolonia API key. This is useful when:
- Using open-source tile servers like OpenStreetMap Japan
- Self-hosting your own tiles and styles
- Distributing maps without API key dependencies
Note: Geolonia API key is only required when using Geolonia's hosted styles and tiles.
<!DOCTYPE html>
<html>
<body>
<!-- Using OpenStreetMap Japan tiles (no API key needed) -->
<!-- Note: tile.openstreetmap.jp is for non-commercial use only -->
<div
class="geolonia"
data-lat="35.6812"
data-lng="139.7671"
data-zoom="14"
data-style="https://tile.openstreetmap.jp/styles/osm-bright/style.json"
></div>
<script src="https://cdn.geolonia.com/embed/v5/embed"></script>
</body>
</html>You can also use npm/unpkg/jsDelivr for self-hosted or CDN distribution:
<!-- Using npm CDN (unpkg) -->
<script src="https://unpkg.com/@geolonia/embed@latest/dist/embed.js"></script>
<!-- Using jsDelivr -->
<script src="https://cdn.jsdelivr.net/npm/@geolonia/embed@latest/dist/embed.js"></script>data-style attribute
The data-style attribute accepts:
- Geolonia style names:
geolonia/basic,geolonia/gsi(requires API key) - Full URLs:
https://example.com/style.json - Relative paths:
./custom-style.json,/styles/my-style.json - Files ending in .json: Automatically resolved to absolute URLs
You can see more examples at https://geolonia.github.io/embed/.
Contributing
Development
Requirements
- node.js >= 22.18
How to build
$ git clone [email protected]:geolonia/embed.git
$ cd embed
$ npm install
$ npm start # run dev server
$ npm test # run tests
$ npm run e2e # run e2e tests
$ npm run build # build production bundleThen you can see http://localhost:3000/.
Run Bundle analyzer
$ npm run analyzeSnapshot testing
preparation
$ cp .envrc.sample .envrc
$ vi .envrc
$ npm run build
$ docker build . -t geolonia/embed