ngx-apple-mapkit

Angular Apple Maps (mapkit.js)

Install 🌐

npm install ngx-apple-mapkit

Demo ‍🧑‍💻

You can test it here:

https://projects.web-timo.de/preview/ngx-apple-mapkit

Before you start 👀

Apple mapkit.js Documentation

Generating JWT token

For generating, you need:

• Team ID
• Maps ID
• MapKit key ID
• MapKit Private key

Get started 🔥

• Add to the index.html script including <script src="https://cdn.apple-mapkit.com/mk/5.x.x/mapkit.js"></script>
• Add AppleMapsModule to imports in your app.module.ts

Map(s) creation ✅

• Define options: MapKitInitOptions in your *.component.ts file
• Define settings: MapConstructorOptions
• Add <ngx-apple-mapkit [options]="options" [settings]="settings"></ngx-apple-mapkit> in your *.component.html

Usage

Map

To start the map, the ngx-apple-mapkit must be described in the HTML component.

<ngx-apple-mapkit (onLoaded)="onLoaded($event)"
                  *ngIf="options && settings"
                  [options]="options" [settings]="settings">
</ngx-apple-mapkit>

export class NgxAppleMapkitComponent implements OnInit, OnDestroy {
    public settings: MapConstructorOptions;
    public options: MapKitInitOptions;
    private map: MapKitLoaded;

    // ...

    ngOnInit(): void {
        const token: string = "YOUR_TOKEN";
        this.initMapkit(token);
    }

    // ...

    private initMapkit(token: string) {
        const dark: boolean = this.themeService.isDark;

        const home = {
            latitude: 51.68,
            longitude: 7.86
        };

        this.settings = {
            colorScheme: dark ? "dark" : "light",
            isZoomEnabled: true,
            showsZoomControl: true,
            showsUserLocationControl: false,
            showsMapTypeControl: true,
            showsUserLocation: false,
            tracksUserLocation: false,
            isScrollEnabled: true,
            mapType: "standard",
            center: home,
            isRotationEnabled: true,
            region: {
                center: home,
                span: {
                    from: 0.050, // Zoom
                    to: 0.050 // Zoom
                }
            }
        };

        this.options = {
            JWT: token, // <-- Here your MapKit Token
            language: window.navigator.language,
            callback: (data: any) => {
                console.log('data ', data);
            }
        };
    }

    onLoaded(e: MapKitLoaded) {
        this.map = e;
    }

    ngOnDestroy(): void {
        this.map?.map?.destroy();
    }
}

Parameter	Typ	Use	Default	Required
[options]	MapKitInitOptions	Needed for Token and Init Option	-	✅
[settings]	MapConstructorOptions	Settings for Apple Maps	-	✅
[logging]	boolean	For Development	false	❌
[language]	"en" | "de" | "es" | "it" | "fr" | string	Set Language	"en"	❌
(onLoaded)	(event: MapKitLoaded) => void;	Return Map	-	❎

Set MapKit Token

As you can see from the previous code examples, the token is set in options.

this.options = {
    JWT: token, // <-- Here your MapKit Token
    language: window.navigator.language,
    callback: (data: any) => {
        console.log('data ', data);
    }
};

Control MapKit

With the ngx-apple-mapkit, you get an object back via the onLoaded that contains the map and some pre-built functions.

<ngx-apple-mapkit-annotation
        ...
        (onLoaded)="onLoaded($event)"
></ngx-apple-mapkit-annotation>

function onLoaded(e: MapKitLoaded) {
    this.map = e;
}

export declare interface MapKitLoaded {
    key: number;
    map: MapKit.Map; // <-- Native mapkit.js Map

    addEventListener<T, K extends keyof MapKit.MapEvents<this>>(
        type: K,
        listener: (this: T, event: MapKit.MapEvents<this>[K]) => void,
        thisObject?: T
    ): void;

    isRotationAvailable: () => boolean;
    isRotationEnabled: () => boolean;
    isScrollEnabled: () => boolean;
    isZoomEnabled: () => boolean;
    getCenter: () => CoordinatesInterface;
    setCenterAnimated: (latitude: number, longitude: number, animate?: boolean) => void;
    getRegion: () => MapKitRegion;
    setRegionAnimated: (center: CoordinatesInterface, span?: SpanInterface, animate?: boolean) => void;
    getRotation: () => number;
    setRotationAnimated: (degrees: number, animate?: boolean) => void;
    getCameraDistance: () => number;
    setCameraDistanceAnimated: (distance: number, animate?: boolean) => void;
    getCameraZoomRange: () => MapKitGetCameraZoomRange;
    setCameraZoomRangeAnimated: (minCameraDistance: number, maxCameraDistance: number, animate?: boolean) => void;
    getColorScheme: () => SchemeString | string;
    setColorScheme: (scheme: SchemeString) => void;
    getDistances: () => DistancesString;
    setDistances: (distance: DistancesString) => void;
    getMapType: () => MapTypeString;
    setMapType: (type: MapTypeString) => void;
    getPadding: () => PaddingInterface;
    setPadding: (padding: PaddingInterface) => void;
    getShowsMapTypeControl: () => boolean;
    setShowsMapTypeControl: (value: boolean) => void;
    getShowsZoomControl: () => boolean;
    setShowsZoomControl: (value: boolean) => void;
    getShowsUserLocationControl: () => boolean;
    setShowsUserLocationControl: (value: boolean) => void;
    getShowsPointsOfInterest: () => boolean;
    setShowsPointsOfInterest: (value: boolean) => void;
    getShowsScale: () => ShowsScaleString;
    setShowsScale: (padding: ShowsScaleString) => void;
    getTintColor: () => string;
    setTintColor: (value: string) => void;
    showItems: (items: MapKitItem | MapKitItem[], mapShowItemOptions?: MapShowItemOptionsInterface) => void;
    getAnnotations: () => Promise<MapKitAnnotation[]>;
    getSelectedAnnotations: () => MapKitGetSelectedAnnotations;
    showsCompass: MapKitCompass;
    showsMapTypeControl: boolean;
    showsZoomControl: boolean;
    showsUserLocationControl: boolean;
    showsPointsOfInterest: boolean;
    tintColor: string;
}

Zoom

Since I can't really integrate the zoom. But there is a workaround for this.

class NgxAppleMapkitComponent {
    // ...

    onLoaded(e: MapKitLoaded) {
        const map: MapKit.Map = e.map;
        (map as any)._impl.zoomLevel = 4; // <-- Zoom Level
    }

    // ...
}

Annotations (Markers)

<ngx-apple-mapkit ...>
   <ngx-apple-mapkit-annotation
           [options]="{title: 'Timo Köhler', subtitle: 'web-timo.de', glyphText: '🧑‍💻', selected: true}"
           (onSelect)="onSelect($event)"
           (onDeselect)="onDeselect($event)"
           [latitude]="51.68"
           [longitude]="7.86"
   ></ngx-apple-mapkit-annotation>
</ngx-apple-mapkit>

Parameter	Typ	Use	Required
[options]	AnnotationConstructorOptionsInterface	For example, name, subtitle or icon are specified there	✅
[latitude]	number	Latitude	✅
[longitude]	number	Longitude	✅
(onSelect)	(event: any) => void;	This is triggered when the user clicks on the marker	❌
(onDeselect)	(event: any) => void;	This is triggered when the user leaves the marker	❌

Custom Selected Marker

<ngx-apple-mapkit ...>
    <ngx-apple-mapkit-annotation ...>
        <div style="background-color: white; padding: 10px; border-radius: 10px; color: red">
            Timo Köhler
        </div>
    </ngx-apple-mapkit-annotation>
</ngx-apple-mapkit>

Typed mapkit.js 😎😍

From version 0.0.24 you can use typed mapkit.js.

This makes it much easier for them to find and use functions themselves rather than having to constantly try them out. Thanks to IDE.

import {MapKit, mapkit} from 'ngx-apple-mapkit';

class NgxAppleMapkitComponent {
    // ...
    onLoaded(e: MapKitLoaded) {
        this.map = e;
        const map: MapKit.Map = e.map;

        const people = [
            {
                title: "Juan Chavez",
                coordinate: new mapkit.Coordinate(37.3349, -122.0090201),
                role: "developer",
                building: "HQ"
            },
            {
                title: "Anne Johnson",
                coordinate: new mapkit.Coordinate(37.722319, -122.434979),
                role: "manager",
                building: "HQ"
            }
        ];

    }

    // ...
}

MapKit: Typed Namespace.

mapkit: Basically the window.mapkit but with MapKit Type.

Service

🛈 I will make these Service functions capable of TypeScript in the coming updates. This is another old circumstance from the predecessor ngx-apple-maps

For using api without map you should initialize API using AppleMapsService

• Init mapkit js using AppleMapsService

this.appleMapsService.init({
    JWT: 'YOUR_TOKEN'
});

Search and autocomplete

Import AppleMapsSearchService

Methods:

1. Search / Autocomplete

1.1 Init search

this.appleMapsSearchService.initSearch(options);

Using search

this.appleMapsSearchService.search(
    query, // search query
    (err, data) => {
    }, // callback
    options // SearchInterface
);

Using autocomplete

this.appleMapsSearchService.autocomplete(
    query, // search query
    (err, data) => {
    }, // callback
    options // SearchInterface
);

SearchInterface

const options = {  // optional
    getsUserLocation: false, // search near user
    coordinate: {
        latitude: number,
        longitude: number,
    },
    language: 'en', // default browser language
    region: {
        center: {
            latitude: number,
            longitude: number,
        },
        span: {
            from: number,
            to: number,
        }
    }
};

2. User location

getUserLocation(timeout)

Return Promise
timeout - Promise.reject() timeout, default 5000 If timeout is 0 reject doesn't call

Geocoder

Import AppleMapsGeocoderService

Methods: reverseLookup(lat, lon, callback, options: GeocoderReverseLookupOptionsInterface)

interface GeocoderReverseLookupOptionsInterface {
    language: string;
}

Angular Universal

Map don't rendering on the server side, all methods unavailable.

Info

ngx-apple-maps ❤️

This is a renewed variant of the ngx-apple-maps. This runs on Angular 16 and Ivy. I personally use the library, and it is therefore regularly maintained.

You can find more information in the original project: github.com/ihor-zinchenko/ngx-apple-maps

⚠️ Important

As of version ngx-apple-mapkit@0.0.24, more significant changes have been made. This has an impact, please pay attention when replacing or updating!