Skip to content

Examples

This page points to the runnable consumer samples that live in the repository.

The direct-API samples are the best starting point if the consumer app owns the canvas and does not want the SDK full UI. The SDK package ships maplibre-gl, so MapLibre GL consumers do not need to add additional tile packages to their own app manifest. For the API-only path, the new MapSdkDirectApiFacade is the easiest single service to inject, MapSdkRequestStateTracker is the helper to reach for when you want stale-response protection in the same flow, and MapSdkRequestViewStateHelper is the smallest shared contract for loading and error UI state. If you want to reduce the vendor-specific tile wiring even further, the MapLibre GL, Mapbox GL, and OpenLayers parcel helpers are the next thing to copy.

Direct API Samples

Location:

  • examples/host-example/direct-api/

The best place to start is the shared sample shell:

  • examples/host-example/direct-api/sample-app/main.ts

Includes:

  • sample-app/ for a small Angular shell with routes for each vendor
  • maplibre-gl/ for a MapLibre GL canvas implementation
  • mapbox-gl/ for a Mapbox GL canvas implementation
  • openlayers/ for an OpenLayers canvas implementation

Sample App File Map

The sample-app/ folder is the entry point that wires the vendor demos together. Each file has a clear job:

  • main.ts bootstraps Angular and starts the sample app
  • app.config.ts provides provideMapSdk(...) once for the whole shell
  • app.routes.ts switches between the vendor demos
  • app.component.ts renders the top-level navigation shell
  • styles.css gives the sample a simple layout for the canvas and details pane

The consumer pattern is the same in a real app. You can transplant the shell, keep the SDK bootstrap, and then replace the sample canvas component with your own page or route.

What The Samples Show

Each sample demonstrates the same integration contract:

  1. bootstrap the SDK once with provideMapSdk(...)
  2. use LocationService to load province and municipality filters
  3. use MapFeatureHttpDataSource for boundary and parcel MVT tile URLs
  4. mount the vendor canvas into the page
  5. create province, district, municipality, suburb, and parcel layers in the app
  6. use MapSdkService.getParcelDetail(...) for parcel click details

That means the sample is not a full SDK page. It is a consumer-owned canvas pattern with the SDK supplying the data and tile URLs.

Suggested Starting Point

If you want to run all three vendor demos from one Angular app, start with the shared shell in:

  • examples/host-example/direct-api/sample-app/main.ts

That shell routes between the vendor examples:

  • /maplibre-gl
  • /mapbox-gl
  • /openlayers

Each route then loads its own vendor canvas service and page component:

  • maplibre-gl/maplibre-gl-map-canvas.service.ts
  • maplibre-gl/maplibre-gl-map-page.component.ts
  • mapbox-gl/mapbox-gl-map-canvas.service.ts
  • mapbox-gl/mapbox-gl-map-page.component.ts
  • openlayers/openlayers-map-canvas.service.ts
  • openlayers/openlayers-map-page.component.ts

If you only need one vendor, you can copy just that folder plus the shared sample-app/ bootstrap pieces.

Packaging Checklist

If you want to treat the sample like a package blueprint instead of a loose set of files, keep these boundaries:

  • copy sample-app/ first as the Angular shell
  • keep app.config.ts as the single provideMapSdk(...) entry point
  • keep app.routes.ts as the vendor router
  • copy one vendor folder at a time when you want to run a specific map engine
  • leave the other vendor folders out until you need them

That gives the consumer app a clean handoff point: the SDK provides the data and tile helpers, while the app provides the canvas, routes, and page shell.

Walkthrough

When you open the shared sample app, the page is arranged like this:

------------------------------------------------------------
Map SDK direct API sample
Vendor canvas demos                     [MapLibre][Mapbox][OpenLayers]
------------------------------------------------------------
| toolbar: province / municipality filters                |
------------------------------------------------------------
| canvas area                      | details / parcel panel |
|                                  |                       |
|                                  |                       |
------------------------------------------------------------

What each area does:

  • the header title identifies the direct-API sample
  • the nav buttons switch between MapLibre GL, Mapbox GL, and OpenLayers routes
  • the toolbar changes province and municipality scope
  • the canvas area is where the vendor map renders province, district, municipality, suburb, and parcel layers
  • the right panel shows clicked parcel details or debug output

How the sample behaves end to end:

  1. the app starts in main.ts
  2. the SDK runtime config is provided in app.config.ts
  3. the shell route decides which vendor page to render
  4. the vendor page mounts its own map canvas
  5. the page loads provinces and municipalities from LocationService
  6. the page builds boundary and parcel tile URLs from MapFeatureHttpDataSource
  7. the canvas receives the tile layers
  8. parcel clicks use MapSdkService.getParcelDetail(...)
  9. the returned detail is displayed in the page-owned panel

This is the pattern to copy when the consumer app wants the API and canvas integration, but not the SDK full UI.

What should happen as you interact:

  1. choose a province
  2. the sample loads the province and related boundary layers
  3. choose a municipality
  4. the sample rebuilds the boundary scope and parcel layer for that municipality
  5. click a parcel on the canvas
  6. the sample asks MapSdkService.getParcelDetail(...) and shows the returned details in the side panel

The same pattern applies to all three vendors. Only the canvas implementation changes.

MapLibre GL  -> bootstrap app -> setScope(...) -> vector tile layers -> click parcel -> load detail
Mapbox GL    -> bootstrap app -> setScope(...) -> vector source tiles -> click parcel -> load detail
OpenLayers   -> bootstrap app -> setScope(...) -> vector tile layers -> click parcel -> load detail

For the longer direct-API explanation, see the Integration Guide.