{"id":25690619,"url":"https://github.com/webtimo-de/ngx-apple-mapkit","last_synced_at":"2025-08-12T12:34:28.482Z","repository":{"id":196975606,"uuid":"687993451","full_name":"webtimo-de/ngx-apple-mapkit","owner":"webtimo-de","description":null,"archived":false,"fork":false,"pushed_at":"2024-04-07T12:48:59.000Z","size":709,"stargazers_count":2,"open_issues_count":1,"forks_count":1,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-07-05T01:48:20.888Z","etag":null,"topics":["angular","angular-maps","apple","apple-maps","mapkit","mapkit-js","maps","ngx-apple-maps"],"latest_commit_sha":null,"homepage":"https://npmjs.com/package/ngx-apple-mapkit","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/webtimo-de.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-09-06T12:35:24.000Z","updated_at":"2024-08-15T09:55:27.000Z","dependencies_parsed_at":null,"dependency_job_id":"8059083c-8df2-45e3-9a00-575f4b1a4138","html_url":"https://github.com/webtimo-de/ngx-apple-mapkit","commit_stats":null,"previous_names":["webtimo-de/ngx-apple-mapkit"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/webtimo-de/ngx-apple-mapkit","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/webtimo-de%2Fngx-apple-mapkit","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/webtimo-de%2Fngx-apple-mapkit/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/webtimo-de%2Fngx-apple-mapkit/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/webtimo-de%2Fngx-apple-mapkit/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/webtimo-de","download_url":"https://codeload.github.com/webtimo-de/ngx-apple-mapkit/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/webtimo-de%2Fngx-apple-mapkit/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":270061551,"owners_count":24520319,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-12T02:00:09.011Z","response_time":80,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["angular","angular-maps","apple","apple-maps","mapkit","mapkit-js","maps","ngx-apple-maps"],"created_at":"2025-02-24T22:50:34.154Z","updated_at":"2025-08-12T12:34:28.452Z","avatar_url":"https://github.com/webtimo-de.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Angular Apple Maps (mapkit.js)\n\n[![npm-version](https://img.shields.io/npm/v/ngx-apple-mapkit.svg?label=npm)](https://www.npmjs.com/package/ngx-apple-mapkit)\n![npm](https://img.shields.io/npm/dw/ngx-apple-mapkit)\n[![license](https://img.shields.io/npm/l/ngx-apple-mapkit.svg)](https://github.com/webtimo-de/ngx-apple-mapkit/blob/master/LICENSE)\n\n## Install 🌐\n\n```shell\nnpm install ngx-apple-mapkit\n```\n\n## Demo ‍🧑‍💻\n\nYou can test it here:\n\nhttps://projects.web-timo.de/preview/ngx-apple-mapkit\n\n## Before you start 👀\n\n[Apple mapkit.js Documentation](https://developer.apple.com/documentation/mapkitjs/mapkit/map)\n\n[Generating JWT token](https://developer.apple.com/documentation/mapkitjs/creating_and_using_tokens_with_mapkit_js?changes=latest_minor)\n\nFor generating, you need:\n\n- Team ID\n- Maps ID\n- MapKit key ID\n- MapKit Private key\n\n## Get started 🔥\n\n1. Add to the `index.html` script including\n   `\u003cscript src=\"https://cdn.apple-mapkit.com/mk/5.x.x/mapkit.js\"\u003e\u003c/script\u003e`\n2. Add `AppleMapsModule` to imports in your `app.module.ts`\n\n## Map(s) creation ✅\n\n1. Define `options: MapKitInitOptions` in your `*.component.ts` file\n2. Define `settings: MapConstructorOptions`\n3. Add `\u003cngx-apple-mapkit [options]=\"options\" [settings]=\"settings\"\u003e\u003c/ngx-apple-mapkit\u003e` in your `*.component.html`\n\n# Usage\n\n## Map\n\nTo start the map, the `ngx-apple-mapkit` must be described in the HTML component.\n\n```html\n\u003cngx-apple-mapkit (onLoaded)=\"onLoaded($event)\"\n                  *ngIf=\"options \u0026\u0026 settings\"\n                  [options]=\"options\" [settings]=\"settings\"\u003e\n\u003c/ngx-apple-mapkit\u003e\n```\n\n```typescript\nexport class NgxAppleMapkitComponent implements OnInit, OnDestroy {\n    public settings: MapConstructorOptions;\n    public options: MapKitInitOptions;\n    private map: MapKitLoaded;\n\n    // ...\n\n    ngOnInit(): void {\n        const token: string = \"YOUR_TOKEN\";\n        this.initMapkit(token);\n    }\n\n    // ...\n\n    private initMapkit(token: string) {\n        const dark: boolean = this.themeService.isDark;\n\n        const home = {\n            latitude: 51.68,\n            longitude: 7.86\n        };\n\n        this.settings = {\n            colorScheme: dark ? \"dark\" : \"light\",\n            isZoomEnabled: true,\n            showsZoomControl: true,\n            showsUserLocationControl: false,\n            showsMapTypeControl: true,\n            showsUserLocation: false,\n            tracksUserLocation: false,\n            isScrollEnabled: true,\n            mapType: \"standard\",\n            center: home,\n            isRotationEnabled: true,\n            region: {\n                center: home,\n                span: {\n                    from: 0.050, // Zoom\n                    to: 0.050 // Zoom\n                }\n            }\n        };\n\n        this.options = {\n            JWT: token, // \u003c-- Here your MapKit Token\n            language: window.navigator.language,\n            callback: (data: any) =\u003e {\n                console.log('data ', data);\n            }\n        };\n    }\n\n    onLoaded(e: MapKitLoaded) {\n        this.map = e;\n    }\n\n    ngOnDestroy(): void {\n        this.map?.map?.destroy();\n    }\n}\n```\n\n| Parameter  | Typ                                             | Use                              | Default | Required |\n|------------|-------------------------------------------------|----------------------------------|---------|----------|\n| [options]  | MapKitInitOptions                               | Needed for Token and Init Option | -       | ✅        |\n| [settings] | MapConstructorOptions                           | Settings for Apple Maps          | -       | ✅        |\n| [logging]  | boolean                                         | For Development                  | false   | ❌        |\n| [language] | \"en\" \\| \"de\" \\| \"es\" \\| \"it\" \\|  \"fr\" \\| string | Set Language                     | \"en\"    | ❌        |\n| (onLoaded) | (event: MapKitLoaded) =\u003e void;                  | Return Map                       | -       | ❎        |\n\n### Set MapKit Token\n\nAs you can see from the previous code examples, the token is set in `options`.\n\n```typescript\nthis.options = {\n    JWT: token, // \u003c-- Here your MapKit Token\n    language: window.navigator.language,\n    callback: (data: any) =\u003e {\n        console.log('data ', data);\n    }\n};\n```\n\n### Control MapKit\n\nWith the `ngx-apple-mapkit`, you get an object back via the onLoaded that contains the map and some pre-built functions.\n\n```html\n\u003cngx-apple-mapkit-annotation\n        ...\n        (onLoaded)=\"onLoaded($event)\"\n\u003e\u003c/ngx-apple-mapkit-annotation\u003e\n```\n\n```typescript\nfunction onLoaded(e: MapKitLoaded) {\n    this.map = e;\n}\n```\n\n```typescript\nexport declare interface MapKitLoaded {\n    key: number;\n    map: MapKit.Map; // \u003c-- Native mapkit.js Map\n\n    addEventListener\u003cT, K extends keyof MapKit.MapEvents\u003cthis\u003e\u003e(\n        type: K,\n        listener: (this: T, event: MapKit.MapEvents\u003cthis\u003e[K]) =\u003e void,\n        thisObject?: T\n    ): void;\n\n    isRotationAvailable: () =\u003e boolean;\n    isRotationEnabled: () =\u003e boolean;\n    isScrollEnabled: () =\u003e boolean;\n    isZoomEnabled: () =\u003e boolean;\n    getCenter: () =\u003e CoordinatesInterface;\n    setCenterAnimated: (latitude: number, longitude: number, animate?: boolean) =\u003e void;\n    getRegion: () =\u003e MapKitRegion;\n    setRegionAnimated: (center: CoordinatesInterface, span?: SpanInterface, animate?: boolean) =\u003e void;\n    getRotation: () =\u003e number;\n    setRotationAnimated: (degrees: number, animate?: boolean) =\u003e void;\n    getCameraDistance: () =\u003e number;\n    setCameraDistanceAnimated: (distance: number, animate?: boolean) =\u003e void;\n    getCameraZoomRange: () =\u003e MapKitGetCameraZoomRange;\n    setCameraZoomRangeAnimated: (minCameraDistance: number, maxCameraDistance: number, animate?: boolean) =\u003e void;\n    getColorScheme: () =\u003e SchemeString | string;\n    setColorScheme: (scheme: SchemeString) =\u003e void;\n    getDistances: () =\u003e DistancesString;\n    setDistances: (distance: DistancesString) =\u003e void;\n    getMapType: () =\u003e MapTypeString;\n    setMapType: (type: MapTypeString) =\u003e void;\n    getPadding: () =\u003e PaddingInterface;\n    setPadding: (padding: PaddingInterface) =\u003e void;\n    getShowsMapTypeControl: () =\u003e boolean;\n    setShowsMapTypeControl: (value: boolean) =\u003e void;\n    getShowsZoomControl: () =\u003e boolean;\n    setShowsZoomControl: (value: boolean) =\u003e void;\n    getShowsUserLocationControl: () =\u003e boolean;\n    setShowsUserLocationControl: (value: boolean) =\u003e void;\n    getShowsPointsOfInterest: () =\u003e boolean;\n    setShowsPointsOfInterest: (value: boolean) =\u003e void;\n    getShowsScale: () =\u003e ShowsScaleString;\n    setShowsScale: (padding: ShowsScaleString) =\u003e void;\n    getTintColor: () =\u003e string;\n    setTintColor: (value: string) =\u003e void;\n    showItems: (items: MapKitItem | MapKitItem[], mapShowItemOptions?: MapShowItemOptionsInterface) =\u003e void;\n    getAnnotations: () =\u003e Promise\u003cMapKitAnnotation[]\u003e;\n    getSelectedAnnotations: () =\u003e MapKitGetSelectedAnnotations;\n    showsCompass: MapKitCompass;\n    showsMapTypeControl: boolean;\n    showsZoomControl: boolean;\n    showsUserLocationControl: boolean;\n    showsPointsOfInterest: boolean;\n    tintColor: string;\n}\n```\n\n#### Zoom\n\nSince I can't really integrate the zoom. But there is a workaround for this.\n\n```typescript\nclass NgxAppleMapkitComponent {\n    // ...\n\n    onLoaded(e: MapKitLoaded) {\n        const map: MapKit.Map = e.map;\n        map._impl.zoomLevel = 4; // \u003c-- Zoom Level\n    }\n\n    // ...\n}\n```\n\n## Annotations (Markers)\n\n```html\n\u003cngx-apple-mapkit ...\u003e\n    \u003cngx-apple-mapkit-annotation\n            [options]=\"{title: 'Timo Köhler', subtitle: 'web-timo.de', glyphText: '🧑‍💻', selected: true}\"\n            (onSelect)=\"onSelect($event)\"\n            (onDeselect)=\"onDeselect($event)\"\n            [latitude]=\"51.68\"\n            [longitude]=\"7.86\"\n    \u003e\u003c/ngx-apple-mapkit-annotation\u003e\n\u003c/ngx-apple-mapkit\u003e\n```\n\n| Parameter    | Typ                                   | Use                                                     | Required |\n|--------------|---------------------------------------|---------------------------------------------------------|----------|\n| [options]    | AnnotationConstructorOptionsInterface | For example, name, subtitle or icon are specified there | ✅        |\n| [latitude]   | number                                | Latitude                                                | ✅        |\n| [longitude]  | number                                | Longitude                                               | ✅        |\n| (onSelect)   | (event: any) =\u003e void;                 | This is triggered when the user clicks on the marker    | ❌        |\n| (onDeselect) | (event: any) =\u003e void;                 | This is triggered when the user leaves the marker       | ❌        |\n\n### Custom Selected Marker\n\n```html\n\u003cngx-apple-mapkit ...\u003e\n    \u003cngx-apple-mapkit-annotation ...\u003e\n        \u003cdiv style=\"background-color: white; padding: 10px; border-radius: 10px; color: red\"\u003e\n            Timo Köhler\n        \u003c/div\u003e\n    \u003c/ngx-apple-mapkit-annotation\u003e\n\u003c/ngx-apple-mapkit\u003e\n```\n\n## Typed mapkit.js 😎😍\n\nFrom version **0.0.24** you can use typed `mapkit.js`.\n\nThis makes it much easier for them to find and use functions themselves rather than having to constantly try them out.\nThanks to IDE.\n\n```typescript\nimport {MapKit, mapkit} from 'ngx-apple-mapkit';\n```\n\n```typescript\nclass NgxAppleMapkitComponent {\n    // ...\n    onLoaded(e: MapKitLoaded) {\n        this.map = e;\n        const map: MapKit.Map = e.map;\n\n        const people = [\n            {\n                title: \"Juan Chavez\",\n                coordinate: new mapkit.Coordinate(37.3349, -122.0090201),\n                role: \"developer\",\n                building: \"HQ\"\n            },\n            {\n                title: \"Anne Johnson\",\n                coordinate: new mapkit.Coordinate(37.722319, -122.434979),\n                role: \"manager\",\n                building: \"HQ\"\n            }\n        ];\n\n    }\n\n    // ...\n}\n```\n\n`MapKit`: Typed Namespace.\n\n`mapkit`: Basically the window.mapkit but with `MapKit` Type.\n\n## Service\n\nFor using api without map you should initialize API using **AppleMapsService**:\n\nInit mapkit js using `AppleMapsService`\n\n```typescript\nthis.appleMapsService.initialize({\n    JWT: 'YOUR_TOKEN'\n});\n```\n\n### Search / Autocomplete\nImport `AppleMapsSearchService`\n\n#### Initialize\n\n```typescript\nthis.appleMapsSearchService.initialize(options);\n```\n\n#### Using Search\n\n```typescript\nconst result: MapKit.SearchResponse = await this.appleMapsSearchService.searchPromised(query, options);\n```\n\n#### Using Autocomplete\n\n```typescript\nconst result: MapKit.SearchAutocompleteResponse = await this.appleMapsSearchService.autocompletePromised(query, options);\n```\n\n### Geocoder\n\nImport `AppleMapsGeocoderService`\n\n#### Initialize\n\n```typescript\nthis.appleMapsGeocoderService.initialize(options);\n```\n\n#### Using Reverse Lookup\n\n```typescript\nconst result: MapKit.GeocoderResponse = await this.appleMapsGeocoderService.reverseLookupPromised(latitude, longitude, options);\n```\n\n## Angular Universal\n\nMap don't rendering on the server side, all methods unavailable.\n\nTip: You can use the Native mapkit.js\n\n# Info\n\n## ngx-apple-maps ❤️\n\nThis is a renewed variant of the [ngx-apple-maps](https://github.com/ihor-zinchenko/ngx-apple-maps). This runs on\nAngular 16 and Ivy. I personally use the library, and it is therefore regularly maintained.\n\nYou can find more information in the original project:\n[github.com/ihor-zinchenko/ngx-apple-maps](https://github.com/ihor-zinchenko/ngx-apple-maps/blob/master/README.md)\n\n## ⚠️ Important\n\nAs of version **ngx-apple-mapkit@0.0.24**, more significant changes have been made.\nThis has an impact, please pay attention when replacing or updating!\n\n## TODO 🎉\n\n- Standalone Angular Component\n- Use MapKit Namespace overall\n- Remove functions in `MapKitLoaded` and directly use mapkit\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwebtimo-de%2Fngx-apple-mapkit","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fwebtimo-de%2Fngx-apple-mapkit","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwebtimo-de%2Fngx-apple-mapkit/lists"}