{"id":37863631,"url":"https://github.com/williamagh/apple-maps-java","last_synced_at":"2026-01-22T07:00:53.297Z","repository":{"id":332735373,"uuid":"1134811558","full_name":"WilliamAGH/apple-maps-java","owner":"WilliamAGH","description":"Easy to use Apple Maps SDK for Java \u0026 Kotlin","archived":false,"fork":false,"pushed_at":"2026-01-17T05:45:53.000Z","size":137,"stargazers_count":2,"open_issues_count":20,"forks_count":0,"subscribers_count":1,"default_branch":"dev","last_synced_at":"2026-01-21T14:25:18.380Z","etag":null,"topics":["api","apple-maps","java","kotlin","sdk","server"],"latest_commit_sha":null,"homepage":"https://central.sonatype.com/artifact/com.williamcallahan/apple-maps-java","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/WilliamAGH.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE.md","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,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-01-15T08:34:54.000Z","updated_at":"2026-01-17T05:42:29.000Z","dependencies_parsed_at":"2026-01-19T03:00:26.937Z","dependency_job_id":null,"html_url":"https://github.com/WilliamAGH/apple-maps-java","commit_stats":null,"previous_names":["williamagh/apple-maps-java"],"tags_count":5,"template":false,"template_full_name":null,"purl":"pkg:github/WilliamAGH/apple-maps-java","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/WilliamAGH%2Fapple-maps-java","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/WilliamAGH%2Fapple-maps-java/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/WilliamAGH%2Fapple-maps-java/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/WilliamAGH%2Fapple-maps-java/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/WilliamAGH","download_url":"https://codeload.github.com/WilliamAGH/apple-maps-java/tar.gz/refs/heads/dev","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/WilliamAGH%2Fapple-maps-java/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28657540,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-22T01:17:37.254Z","status":"online","status_checked_at":"2026-01-22T02:00:07.137Z","response_time":144,"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":["api","apple-maps","java","kotlin","sdk","server"],"created_at":"2026-01-16T16:34:47.893Z","updated_at":"2026-01-22T07:00:53.246Z","avatar_url":"https://github.com/WilliamAGH.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Apple Maps SDK for Java (Server)\n\nA lightweight Java SDK for the Apple Maps Server API, with automatic access-token exchange/refresh.\n\n## Requirements\n\n- Java 17+\n- Apple Developer Program membership (to create a Maps Identifier + private key).\n- A long-lived Apple Maps authorization token (JWT). More: `docs/authorization.md`.\n\n## Installation\n\nReplace `0.1.3` with the latest release.\n\nNote: this repo’s build uses a Gradle Java toolchain (Java 17). If you don’t have JDK 17 installed locally, Gradle will download it automatically.\n\n### Gradle\n\n```groovy\ndependencies {\n    implementation(\"com.williamcallahan:apple-maps-java:0.1.3\")\n}\n```\n\n### Maven\n\n```xml\n\u003cdependency\u003e\n  \u003cgroupId\u003ecom.williamcallahan\u003c/groupId\u003e\n  \u003cartifactId\u003eapple-maps-java\u003c/artifactId\u003e\n  \u003cversion\u003e0.1.3\u003c/version\u003e\n\u003c/dependency\u003e\n```\n\n## Configure `APPLE_MAPS_TOKEN`\n\nOption A (recommended): environment variable\n\n```bash\nexport APPLE_MAPS_TOKEN=\"your-token\"\n```\n\nor via a JVM system property\n\n```bash\njava -DAPPLE_MAPS_TOKEN=\"your-token\" -jar your-app.jar\n```\n\nOption B (local dev for this repo): `.env` fallback\n\n```bash\ncp .env-example .env\n```\n\nThen set `APPLE_MAPS_TOKEN=...` in `.env`. This repo’s Gradle build loads `.env` into system properties (useful for running integration tests locally). `.env` is ignored by git.\n\n## Verify your token (integration test)\n\nRun the live integration test suite:\n\n```bash\n./gradlew testDetail --tests com.williamcallahan.applemaps.AppleMapsIT\n```\n\nOr run a single “smoke test”:\n\n```bash\n./gradlew testDetail --tests com.williamcallahan.applemaps.AppleMapsIT.geocodeHandlesPartialAndFullAddresses\n```\n\nOr run a one-off CLI query:\n\n```bash\n./gradlew cli --args='geocode \"880 Harrison St, San Francisco, CA 94107\"'\n```\n\nMore:\n- Integration tests: `docs/tests.md`\n- CLI usage: `docs/cli.md`\n\n## Example: geocode Startup HQ (San Francisco)\n\n```java\nString token = System.getenv(\"APPLE_MAPS_TOKEN\");\nif (token == null || token.isBlank()) {\n    token = System.getProperty(\"APPLE_MAPS_TOKEN\");\n}\nif (token == null || token.isBlank()) {\n    throw new IllegalStateException(\"Set APPLE_MAPS_TOKEN (env var) or APPLE_MAPS_TOKEN (system property).\");\n}\n\nAppleMaps api = new AppleMaps(token);\nPlaceResults results = api.geocode(GeocodeInput.builder(\"880 Harrison St, San Francisco, CA 94107\").build());\nSystem.out.println(results);\n```\n\nExample response (trimmed):\n\n```json\n{\n  \"results\": [\n    {\n      \"name\": \"880 Harrison St\",\n      \"coordinate\": {\n        \"latitude\": 37.7796095,\n        \"longitude\": -122.4016725\n      },\n      \"formattedAddressLines\": [\n        \"880 Harrison St\",\n        \"San Francisco, CA  94107\",\n        \"United States\"\n      ],\n      \"structuredAddress\": {\n        \"administrativeArea\": \"California\",\n        \"administrativeAreaCode\": \"CA\",\n        \"locality\": \"San Francisco\",\n        \"postCode\": \"94107\",\n        \"subLocality\": \"Yerba Buena\",\n        \"thoroughfare\": \"Harrison St\",\n        \"subThoroughfare\": \"880\",\n        \"fullThoroughfare\": \"880 Harrison St\",\n        \"dependentLocalities\": [\n          \"Yerba Buena\"\n        ]\n      },\n      \"countryCode\": \"US\"\n    }\n  ]\n}\n```\n\n## What’s included\n\n- Geocode + reverse geocode\n- Search + autocomplete (and `resolveCompletionUrls`)\n- Directions + ETA\n- Place lookup + alternate IDs\nMore examples: `docs/usage.md`\n\nCommon use case: business / startup search (name-only or name + address) via Search + Autocomplete.\n\n## Compatibility\n\n- Java (server/JVM): usable from any modern JVM app (for example Spring Boot, Spring AI, Quarkus, or plain Java) as long as you run on a compatible JDK.\n- Target bytecode: built for Java 17 classfiles, so consuming projects must run on JDK 17+ (including JDK 25).\n- Kotlin/JVM: works like any other Maven dependency (same JVM/JDK requirement as above).\n- Android: not supported as-is because this library uses `java.net.http.HttpClient` (not part of the standard Android runtime).\n- Kotlin Multiplatform (KMP) / iOS: KMP is a popular way to write Kotlin that runs on iOS, but iOS uses Kotlin/Native (not a JVM), so it cannot consume JVM bytecode artifacts like this. To support iOS, this would need a KMP-native implementation (for example using Ktor client) and publishing a multiplatform artifact.\n\n## Quota (included limits)\n\nApple provides daily quotas per Apple Developer Program membership (for example, a service-call limit shared between MapKit JS service requests and Apple Maps Server API calls). When you exceed the daily service-call quota, Apple responds with HTTP `429 Too Many Requests`. Apple does not provide a self-serve way to purchase additional quota; for extra capacity, contact Apple via the Maps developer dashboard. https://maps.developer.apple.com/\n\n## More from the author\n\n[William Callahan](https://williamcallahan.com)\n\n- [TUI4J](https://github.com/WilliamAGH/tui4j) (a modern TUI library for Java)\n- [Brief](https://github.com/WilliamAGH/brief) (an open-source terminal AI chat app in Java)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwilliamagh%2Fapple-maps-java","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fwilliamagh%2Fapple-maps-java","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwilliamagh%2Fapple-maps-java/lists"}