### Request Directions using curl Source: https://developer.apple.com/documentation/applemapsserverapi/-v1-directions Example of how to request directions using curl. Ensure you replace with your valid token. ```bash curl -si -H "Authorization: Bearer " \ "https://maps-api.apple.com/v1/directions?origin=37.7857,-122.4011&destination=San Francisco City Hall, CA" ``` -------------------------------- ### Directions API Response Example Source: https://developer.apple.com/documentation/applemapsserverapi/-v1-directions A sample JSON response from the Directions API, detailing destination information, routes, and turn-by-turn steps. ```json { "destination": { "center": { "latitude": 37.7753881, "longitude": -122.3931773 }, "displayMapRegion": { "southLatitude": 37.7708965235794, "westLongitude": -122.39885983149095, "northLatitude": 37.7798796764206, "eastLongitude": -122.38749476850906 }, "name": "San Francisco Public Library - Mission Bay", "formattedAddressLines": [ "960 4th St", "San Francisco, CA 94158", "United States" ], "structuredAddress": { "administrativeArea": "California", "subAdministrativeArea": "San Francisco County", "administrativeAreaCode": "CA", "locality": "San Francisco", "postCode": "94158", "subLocality": "Mission Bay North", "thoroughfare": "4th St", "subThoroughfare": "960", "fullThoroughfare": "960 4th St", "dependentLocalities": [ "Mission Bay North", "Mission Bay" ] }, "country": "United States", "countryCode": "US", "telephone": "+14153552838", "urls": [ "https://sfpl.org/locations/mission-bay" ] }, "routes": [ { "name": "4th St", "distanceMeters": 2033, "durationSeconds": 506, "transportType": "AUTOMOBILE", "stepIndexes": [ 0, 1, 2, 3, 4, 5, 6, 7 ], "hasTolls": true }, { "name": "2nd St", "distanceMeters": 2342, "durationSeconds": 592, "transportType": "AUTOMOBILE", "stepIndexes": [ 8, 9, 10, 11, 12, 13 ], "hasTolls": true }, { "name": "Harrison St", "distanceMeters": 2029, "durationSeconds": 548, "transportType": "AUTOMOBILE", "stepIndexes": [ 14, 15, 16, 17, 18, 19, 20, 21, 22, 23 ], "hasTolls": true } ], "steps": [ { "stepPathIndex": 0, "distanceMeters": 0, "durationSeconds": 0 }, { "stepPathIndex": 1, "distanceMeters": 37, "durationSeconds": 11, "instructions": "Turn right onto Minna St" }, { "stepPathIndex": 2, "distanceMeters": 188, "durationSeconds": 76, "instructions": "Turn right onto New Montgomery St" }, { "stepPathIndex": 3, "distanceMeters": 127, "durationSeconds": 27, "instructions": "Turn right onto Howard St" }, { "stepPathIndex": 4, "distanceMeters": 468, "durationSeconds": 104, "instructions": "Turn left onto 4th St" }, { "stepPathIndex": 5, "distanceMeters": 446, "durationSeconds": 71, "instructions": "Keep right onto 4th St" }, { "stepPathIndex": 6, "distanceMeters": 136, "durationSeconds": 48, "instructions": "Keep right onto 4th St" }, { "stepPathIndex": 7, "distanceMeters": 633, "durationSeconds": 169, "instructions": "The destination is on your right" }, { "stepPathIndex": 8, "distanceMeters": 0, "durationSeconds": 0 }, { "stepPathIndex": 9, "distanceMeters": 98, "durationSeconds": 38, "instructions": "Turn right onto Mission St" }, { "stepPathIndex": 10, "distanceMeters": 279, "durationSeconds": 81, "instructions": "Turn right onto 2nd St" }, { "stepPathIndex": 11, "distanceMeters": 1265, "durationSeconds": 282, "instructions": "Turn right onto King St" }, { "stepPathIndex": 12, "distanceMeters": 589, "durationSeconds": 156, "instructions": "Turn left onto 4th St" }, { "stepPathIndex": 13, "distanceMeters": 112, "durationSeconds": 36, "instructions": "The destination is on your right" }, { "stepPathIndex": 14, "distanceMeters": 0, "durationSeconds": 0 }, { "stepPathIndex": 15, "distanceMeters": 37, "durationSeconds": 11, "instructions": "Turn right onto Minna St" }, { "stepPathIndex": 16, "distanceMeters": 188, "durationSeconds": 76, "instructions": "Turn right onto New Montgomery St" }, { "stepPathIndex": 17, "distanceMeters": 127, "durationSeconds": 26, "instructions": "Turn right onto Howard St" }, { "stepPathIndex": 18, "distanceMeters": 50, "durationSeconds": 18, "instructions": "Turn left onto Hawthorne St" }, { "stepPathIndex": 19, "distanceMeters": 384, "durationSeconds": 107, "instructions": "Turn right onto Harrison St" }, { "stepPathIndex": 20, "distanceMeters": 468, "durationSeconds": 104, "instructions": "Turn left onto 4th St" }, { "stepPathIndex": 21, "distanceMeters": 446, "durationSeconds": 71, "instructions": "Keep right onto 4th St" }, { "stepPathIndex": 22, "distanceMeters": 136, "durationSeconds": 48, "instructions": "Keep right onto 4th St" }, { "stepPathIndex": 23, "distanceMeters": 633, "durationSeconds": 169, "instructions": "The destination is on your right" } ] } ``` -------------------------------- ### Reverse Geocode Response Example Source: https://developer.apple.com/documentation/applemapsserverapi/-v1-reversegeocode This is an example of a successful JSON response from the reverse geocode endpoint, containing address details for the provided coordinates. ```json { "results": [ { "coordinate": { "latitude": 37.3301996, "longitude": -122.0106415 }, "displayMapRegion": { "southLatitude": 37.3257080235794, "westLongitude": -122.01629018770203, "northLatitude": 37.3346911764206, "eastLongitude": -122.00499281229798 }, "name": "Apple Park Way", "formattedAddressLines": [ "Apple Park Way", "Cupertino, CA 95014", "United States" ], "structuredAddress": { "administrativeArea": "California", "administrativeAreaCode": "CA", "locality": "Cupertino", "postCode": "95014", "thoroughfare": "Apple Park Way", "fullThoroughfare": "Apple Park Way", "areasOfInterest": [ "Apple Park" ] }, "country": "United States", "countryCode": "US" } ] } ``` -------------------------------- ### ETA Response Example Source: https://developer.apple.com/documentation/applemapsserverapi/-v1-etas This JSON structure represents a successful response from the ETAs endpoint, detailing travel information for each destination. ```json { "etas": [ { "destination": { "latitude": 37.32556561130194, "longitude": -121.94635203581443 }, "transportType": "AUTOMOBILE", "distanceMeters": 9550, "expectedTravelTimeSeconds": 975, "staticTravelTimeSeconds": 540 }, { "destination": { "latitude": 37.44176585512703, "longitude": -122.17259315798667 }, "transportType": "AUTOMOBILE", "distanceMeters": 23286, "expectedTravelTimeSeconds": 1336, "staticTravelTimeSeconds": 1039 } ] } ``` -------------------------------- ### Decode JWT Headers Source: https://developer.apple.com/documentation/applemapsserverapi/debugging-an-invalid-token Use this command-line example to decode the headers of a JWT token and check for duplicate fields like 'kid'. ```bash % echo "your-token-here" | tr "." "\n" | head -2 | base64 -D // Prints // {"typ":"JWT","alg":"ES256","kid":"KEY_ID","kid":"KEY_ID"} ``` -------------------------------- ### Example Waypoints for Directions Source: https://developer.apple.com/documentation/applemapsserverapi/-v1-directions This snippet shows the structure for providing latitude and longitude coordinates as waypoints for a directions request. Ensure coordinates are accurate for precise routing. ```json { "latitude": 37.776182, "longitude": -122.393998 }, { "latitude": 37.775764, "longitude": -122.393485 }, { "latitude": 37.775721, "longitude": -122.393403 }, { "latitude": 37.775503, "longitude": -122.393056 } ] ] } ``` -------------------------------- ### DirectionsResponse Object Source: https://developer.apple.com/documentation/applemapsserverapi/directionsresponse Represents the directions from a starting location to a destination, detailing routes, steps, and waypoints. ```APIDOC ## DirectionsResponse An object that describes the directions from a starting location to a destination in terms routes, steps, and a series of waypoints. ### Properties `destination` (Place) - A `Place` object that describes the destination. `origin` (Place) - A `Place` result that describes the origin. `routes` (Array of DirectionsResponse.Route) - An array of routes. Each route references steps based on indexes into the steps array. `stepPaths` (Array of Location) - An array of step paths across all steps across all routes. Each step path is a single polyline represented as an array of points. You reference the step paths by index into the array. `steps` (Array of DirectionsResponse.Step) - An array of all steps across all routes. You reference the route steps by index into this array. Each step in turn references its path based on indexes into the `stepPaths` array. ``` -------------------------------- ### Search for a place using curl Source: https://developer.apple.com/documentation/applemapsserverapi/-v1-search Use curl to send a GET request to the /v1/search endpoint with a query parameter. Include your access token in the Authorization header. ```bash curl -si -H "Authorization: Bearer " "https://maps-api.apple.com/v1/search?q=eiffel%20tower" ``` -------------------------------- ### Search Autocomplete Request Source: https://developer.apple.com/documentation/applemapsserverapi/-v1-searchautocomplete Example of a cURL request to the search autocomplete endpoint. This is useful for testing and understanding the API's input parameters. ```shell curl -si -H "Authorization: Bearer " \ "https://maps-api.apple.com/v1/searchAutocomplete?q=museum&searchLocation=37.7753881,-122.3931773" ``` -------------------------------- ### Search Autocomplete Response Example Source: https://developer.apple.com/documentation/applemapsserverapi/-v1-searchautocomplete This JSON snippet represents a partial response from the Apple Maps Server API's search autocomplete endpoint. It includes address components for a suggested location. ```json { "locality": "San Francisco", "postCode": "94103", "subLocality": "Yerba Buena", "thoroughfare": "Clementina St", "subThoroughfare": "355", "fullThoroughfare": "355 Clementina St", "dependentLocalities": [ "Yerba Buena" ] } } ] } ``` -------------------------------- ### Search Autocomplete Response Source: https://developer.apple.com/documentation/applemapsserverapi/-v1-searchautocomplete Example JSON response from the search autocomplete endpoint, showing potential place completions and their display lines. This response structure is crucial for building user-friendly search interfaces. ```json { "results": [ { "completionUrl": "/v1/search?q=Museums%20For%20Art", "displayLines": [ "Museums For Art", "Search Nearby" ] }, { "completionUrl": "/v1/search?q=Museum", "displayLines": [ "Museum", "Search Nearby" ] }, { "completionUrl": "/v1/search?q=Museum%20of%20Modern%20Art%20151%203rd%20St%2C%20San%20Francisco%2C%20CA%20%2094103%2C%20United%20States&metadata=ChwKFE11c2V1bSBvZiBNb2Rlcm4gQXJ0EgQIABAGEjUKMzE1MSAzcmQgU3QsIFNhbiBGcmFuY2lzY28sIENBICA5NDEwMywgVW5pdGVkIFN0YXRlcxgBKiIKEgkAAABAk%2BRCQBEAAACAq5lewBCElsC359Tk1PMBGK5NYggKBm11c2V1bYLxBAZtdXNldW2I8QQA2vEEFgkAAAAgEYb1PxEAAABgZmDCQDICZW7q8QQA", "displayLines": [ "Museum of Modern Art", "151 3rd St, San Francisco, CA 94103, United States" ], "location": { "lat": 37.785743713378906, "lng": -122.40109252929688 }, "structuredAddress": { "administrativeArea": "California", "subAdministrativeArea": "San Francisco County", "administrativeAreaCode": "CA", "locality": "San Francisco", "postCode": "94103", "subLocality": "Financial District South", "thoroughfare": "3rd St", "subThoroughfare": "151", "fullThoroughfare": "151 3rd St", "areasOfInterest": [ "San Francisco Museum of Modern Art" ], "dependentLocalities": [ "Financial District South", "Yerba Buena", "FiDiSo" ] } }, { "completionUrl": "/v1/search?q=de%20Young%20museum%2050%20Hagiwara%20Tea%20Garden%20Dr%2C%20San%20Francisco%2C%20CA%2094118%2C%20United%20States&metadata=ChcKD2RlIFlvdW5nIG11c2V1bRIECAkQBhJDCkE1MCBIYWdpd2FyYSBUZWEgR2FyZGVuIERyLCBTYW4gRnJhbmNpc2NvLCBDQSA5NDExOCwgVW5pdGVkIFN0YXRlcxgBKiIKEgkAAACgv%2BJCQBEAAABA%2F51ewBCn%2FY68hI664YIBGK5NYggKBm11c2V1bYLxBAZtdXNldW2I8QQA2vEEFgkAAADAN5waQBEAAACACwPBQDICZW7q8QQA", "displayLines": [ "de Young museum", "50 Hagiwara Tea Garden Dr, San Francisco, CA 94118, United States" ], "location": { "lat": 37.7714729309082, "lng": -122.46870422363281 }, "structuredAddress": { "administrativeArea": "California", "subAdministrativeArea": "San Francisco", "administrativeAreaCode": "CA", "locality": "San Francisco", "postCode": "94118", "thoroughfare": "Hagiwara Tea Garden Dr", "subThoroughfare": "50", "fullThoroughfare": "50 Hagiwara Tea Garden Dr", "dependentLocalities": [ "San Francisco", "Bay Area", "Golden Gate" ] } }, { "completionUrl": "/v1/search?q=Asian%20Art%20Museum%20200%20Larkin%20St%2C%20San%20Francisco%2C%20CA%2094102%2C%20United%20States&metadata=ChgKEEFzaWFuIEFydCBNdXNldW0SBAgKEAYSNwo1MjAwIExhcmtpbiBTdCwgU2FuIEZyYW5jaXNjbywgQ0EgOTQxMDIsIFVuaXRlZCBTdGF0ZXMYASoiChIJAAAA4N%2FjQkARAAAAoKKaXsAQkNqC2ruqrLGyARiuTWIICgZtdXNldW2C8QQGbXVzZXVtiPEEANrxBBYJAAAAACS%2BAEARAAAAQApCn0AyAmVu6vEEAA%3D%3D", "displayLines": [ "Asian Art Museum", "200 Larkin St, San Francisco, CA 94102, United States" ], "location": { "lat": 37.780269622802734, "lng": -122.41617584228516 }, "structuredAddress": { "administrativeArea": "California", "subAdministrativeArea": "San Francisco", "administrativeAreaCode": "CA", "locality": "San Francisco", "postCode": "94102", "subLocality": "Tenderloin", "thoroughfare": "Larkin St", "subThoroughfare": "200", "fullThoroughfare": "200 Larkin St", "dependentLocalities": [ "NoMa", "Civic Center", "Tenderloin" ] } }, { "completionUrl": "/v1/search?q=Museum%20of%20the%20Eye%20645%20Beach%20St%2C%20San%20Francisco%2C%20CA%2094109%2C%20United%20States&metadata=ChkKEU11c2V1bSBvZiB0aGUgRXllEgQIABAGEjYKNDY0NSBCZWFjaCBTdCwgU2FuIEZyYW5jaXNjbywgQ0EgOTQxMDksIFVuaXRlZCBTdGF0ZXMYASohChIJAAAAwDrnQkARAAAAwOCaXsAQwuvrgpbHydkJGK5NYggKBm11c2V1bYLxBAZtdXNldW2I8QQA2vEEFgkAAACgB7sQQBEAAADgo4BXQDICZW7q8QQA", "displayLines": [ "Museum of the Eye", "645 Beach St, San Francisco, CA 94109, United States" ], "location": { "lat": 37.806480407714844, "lng": -122.41996765136719 }, "structuredAddress": { "administrativeArea": "California", "subAdministrativeArea": "San Francisco", "administrativeAreaCode": "CA", "locality": "San Francisco", "postCode": "94109", "subLocality": "Fisherman’s Wharf", "thoroughfare": "Beach St", "subThoroughfare": "645" } } ] } ``` -------------------------------- ### Reverse Geocode Request Example Source: https://developer.apple.com/documentation/applemapsserverapi/-v1-reversegeocode Use this cURL command to send a request to the reverse geocode endpoint. Replace with your actual token. ```curl curl -si -H "Authorization: Bearer " "https://maps-api.apple.com/v1/reverseGeocode?loc=37.3301996%2C-122.0106415" ``` -------------------------------- ### Maps Server API Token Header and Payload Structure Source: https://developer.apple.com/documentation/applemapsserverapi/creating-and-using-tokens-with-maps-server-api This example shows the structure of a decoded Maps token, illustrating the required fields for the header and payload. The header specifies signing algorithm, key ID, and token type, while the payload includes issuer, issuance time, expiration time, scope, and origin. ```json { "alg": "ES256", "kid": "ABC123DEFG", "typ": "JWT" } { "iss": "DEF123GHIJ", "iat": 1437179036, "exp": 1493298100, "scope": "server_api", "origin": "*.example.com" } ``` -------------------------------- ### GET Request URL for Place Search by ID Source: https://developer.apple.com/documentation/applemapsserverapi/-v1-place-%3Aid Use this URL to request information about a specific place using its ID. Ensure you replace ':id' with the actual Place ID. ```HTTP GET https://maps-api.apple.com/v1/place/:id ``` -------------------------------- ### Get Estimated Arrival Times and Distances Source: https://developer.apple.com/documentation/applemapsserverapi/-v1-etas Use this cURL command to request estimated travel times and distances from an origin to multiple destinations. Ensure you replace with your valid token. ```bash curl -si -H "Authorization: Bearer " "https://maps-api.apple.com/v1/etas?origin=37.331423,-122.030503&destinations=37.32556561130194,-121.94635203581443|37.44176585512703,-122.17259315798667" ``` -------------------------------- ### GET Request for Alternate Place IDs Source: https://developer.apple.com/documentation/applemapsserverapi/-v1-place-alternateids Use this endpoint to retrieve a list of alternate Place IDs for a given set of Place IDs. Ensure you include the required 'ids' query parameter. ```HTTP GET https://maps-api.apple.com/v1/place/alternateIds ``` -------------------------------- ### Get Directions Source: https://developer.apple.com/documentation/applemapsserverapi/-v1-directions Retrieves driving directions between an origin and a destination. The response includes various route options, total distance, estimated travel time, and detailed steps for each route. ```APIDOC ## GET /v1/directions ### Description Retrieves driving directions between an origin and a destination. The response includes various route options, total distance, estimated travel time, and detailed steps for each route. ### Method GET ### Endpoint /v1/directions ### Parameters #### Query Parameters - **origin** (string) - Required - The starting point for the directions. Can be coordinates (latitude,longitude) or a place name. - **destination** (string) - Required - The ending point for the directions. Can be coordinates (latitude,longitude) or a place name. ### Request Example ``` curl -si -H "Authorization: Bearer " \ "https://maps-api.apple.com/v1/directions?origin=37.7857,-122.4011&destination=San Francisco City Hall, CA" ``` ### Response #### Success Response (200) - **destination** (object) - Information about the destination. - **center** (object) - **latitude** (number) - **longitude** (number) - **displayMapRegion** (object) - **southLatitude** (number) - **westLongitude** (number) - **northLatitude** (number) - **eastLongitude** (number) - **name** (string) - **formattedAddressLines** (array of strings) - **structuredAddress** (object) - **administrativeArea** (string) - **subAdministrativeArea** (string) - **administrativeAreaCode** (string) - **locality** (string) - **postCode** (string) - **subLocality** (string) - **thoroughfare** (string) - **subThoroughfare** (string) - **fullThoroughfare** (string) - **dependentLocalities** (array of strings) - **country** (string) - **countryCode** (string) - **telephone** (string) - **urls** (array of strings) - **routes** (array of objects) - An array of available routes. - **name** (string) - **distanceMeters** (number) - **durationSeconds** (number) - **transportType** (string) - **stepIndexes** (array of numbers) - **hasTolls** (boolean) - **steps** (array of objects) - Detailed steps for the directions. - **stepPathIndex** (number) - **distanceMeters** (number) - **durationSeconds** (number) - **instructions** (string) #### Response Example ```json { "destination": { "center": { "latitude": 37.7753881, "longitude": -122.3931773 }, "displayMapRegion": { "southLatitude": 37.7708965235794, "westLongitude": -122.39885983149095, "northLatitude": 37.7798796764206, "eastLongitude": -122.38749476850906 }, "name": "San Francisco Public Library - Mission Bay", "formattedAddressLines": [ "960 4th St", "San Francisco, CA 94158", "United States" ], "structuredAddress": { "administrativeArea": "California", "subAdministrativeArea": "San Francisco County", "administrativeAreaCode": "CA", "locality": "San Francisco", "postCode": "94158", "subLocality": "Mission Bay North", "thoroughfare": "4th St", "subThoroughfare": "960", "fullThoroughfare": "960 4th St", "dependentLocalities": [ "Mission Bay North", "Mission Bay" ] }, "country": "United States", "countryCode": "US", "telephone": "+14153552838", "urls": [ "https://sfpl.org/locations/mission-bay" ] }, "routes": [ { "name": "4th St", "distanceMeters": 2033, "durationSeconds": 506, "transportType": "AUTOMOBILE", "stepIndexes": [ 0, 1, 2, 3, 4, 5, 6, 7 ], "hasTolls": true }, { "name": "2nd St", "distanceMeters": 2342, "durationSeconds": 592, "transportType": "AUTOMOBILE", "stepIndexes": [ 8, 9, 10, 11, 12, 13 ], "hasTolls": true }, { "name": "Harrison St", "distanceMeters": 2029, "durationSeconds": 548, "transportType": "AUTOMOBILE", "stepIndexes": [ 14, 15, 16, 17, 18, 19, 20, 21, 22, 23 ], "hasTolls": true } ], "steps": [ { "stepPathIndex": 0, "distanceMeters": 0, "durationSeconds": 0 }, { "stepPathIndex": 1, "distanceMeters": 37, "durationSeconds": 11, "instructions": "Turn right onto Minna St" }, { "stepPathIndex": 2, "distanceMeters": 188, "durationSeconds": 76, "instructions": "Turn right onto New Montgomery St" }, { "stepPathIndex": 3, "distanceMeters": 127, "durationSeconds": 27, "instructions": "Turn right onto Howard St" }, { "stepPathIndex": 4, "distanceMeters": 468, "durationSeconds": 104, "instructions": "Turn left onto 4th St" }, { "stepPathIndex": 5, "distanceMeters": 446, "durationSeconds": 71, "instructions": "Keep right onto 4th St" }, { "stepPathIndex": 6, "distanceMeters": 136, "durationSeconds": 48, "instructions": "Keep right onto 4th St" }, { "stepPathIndex": 7, "distanceMeters": 633, "durationSeconds": 169, "instructions": "The destination is on your right" }, { "stepPathIndex": 8, "distanceMeters": 0, "durationSeconds": 0 }, { "stepPathIndex": 9, "distanceMeters": 98, "durationSeconds": 38, "instructions": "Turn right onto Mission St" }, { "stepPathIndex": 10, "distanceMeters": 279, "durationSeconds": 81, "instructions": "Turn right onto 2nd St" }, { "stepPathIndex": 11, "distanceMeters": 1265, "durationSeconds": 282, "instructions": "Turn right onto King St" }, { "stepPathIndex": 12, "distanceMeters": 589, "durationSeconds": 156, "instructions": "Turn left onto 4th St" }, { "stepPathIndex": 13, "distanceMeters": 112, "durationSeconds": 36, "instructions": "The destination is on your right" }, { "stepPathIndex": 14, "distanceMeters": 0, "durationSeconds": 0 }, { "stepPathIndex": 15, "distanceMeters": 37, "durationSeconds": 11, "instructions": "Turn right onto Minna St" }, { "stepPathIndex": 16, "distanceMeters": 188, "durationSeconds": 76, "instructions": "Turn right onto New Montgomery St" }, { "stepPathIndex": 17, "distanceMeters": 127, "durationSeconds": 26, "instructions": "Turn right onto Howard St" }, { "stepPathIndex": 18, "distanceMeters": 50, "durationSeconds": 18, "instructions": "Turn left onto Hawthorne St" }, { "stepPathIndex": 19, "distanceMeters": 384, "durationSeconds": 107, "instructions": "Turn right onto Harrison St" } ] } ``` ``` -------------------------------- ### Determine estimated arrival times and distances Source: https://developer.apple.com/documentation/applemapsserverapi/-v1-etas Returns the estimated time of arrival (ETA) and distance between starting and ending locations. This endpoint is available for Apple Maps Server API version 1.2 and later. ```APIDOC ## GET https://maps-api.apple.com/v1/etas ### Description Returns the estimated time of arrival (ETA) and distance between starting and ending locations. ### Method GET ### Endpoint https://maps-api.apple.com/v1/etas ### Query Parameters #### Path Parameters None #### Query Parameters - **origin** (string) - Required - The starting point for estimated arrival time requests, specified as a comma-separated string that contains the latitude and longitude. For example, `origin=37.331423,-122.030503`. - **destinations** (string) - Required - Destination coordinates represented as pairs of latitude and longitude separated by a vertical bar character (”|”). For example, `destinations=37.32556561130194,-121.94635203581443|37.44176585512703,-122.17259315798667`. The parameter must specify at least one destination coordinate, but no more than 10 destinations. Specify the location as a comma-separated string that contains the latitude and longitude. - **transportType** (string) - Optional - The mode of transportation to use when estimating arrival times. Default: `Automobile`. Possible Values: `Automobile, Transit, Walking, Cycling`. - **departureDate** (string) - Optional - The time of departure to use in an estimated arrival time request, in ISO 8601 format in UTC time. For example, `departureDate=2020-09-15T16:42:00Z`. If not specified, the server uses the current date and time. - **arrivalDate** (string) - Optional - The intended time of arrival in ISO 8601 format in UTC time. ### Request Example ```bash curl -si -H "Authorization: Bearer " "https://maps-api.apple.com/v1/etas?origin=37.331423,-122.030503&destinations=37.32556561130194,-121.94635203581443|37.44176585512703,-122.17259315798667" ``` ### Response #### Success Response (200 OK) An array of `EtaResponse` objects that contain distance and time from the origin to each destination. ```json { "etas": [ { "destination": { "latitude": 37.32556561130194, "longitude": -121.94635203581443 }, "transportType": "AUTOMOBILE", "distanceMeters": 9550, "expectedTravelTimeSeconds": 975, "staticTravelTimeSeconds": 540 }, { "destination": { "latitude": 37.44176585512703, "longitude": -122.17259315798667 }, "transportType": "AUTOMOBILE", "distanceMeters": 23286, "expectedTravelTimeSeconds": 1336, "staticTravelTimeSeconds": 1039 } ] } ``` #### Error Responses - **400 Bad Request**: An `ErrorResponse` object that contains an error message and an array of strings that contain additional details. - **401 Unauthorized**: An `ErrorResponse` object that contains an error message indicating the Maps access token is missing or invalid, and an array of strings that contain additional details about the error. - **429 Too Many Requests**: An `ErrorResponse` object that indicates the call exceeds the daily service call quota for the authorization token presented. The app should try again later. - **500 Internal Server Error**: An `ErrorResponse` object that contains a server error message and an array of strings that describe additional details about the error. ``` -------------------------------- ### GET Request URL for Place Search Source: https://developer.apple.com/documentation/applemapsserverapi/-v1-place This is the base URL for searching places using multiple identifiers. Ensure you are using Apple Maps Server API version 1.2 or later. ```HTTP GET https://maps-api.apple.com/v1/place ``` -------------------------------- ### Obtain a list of alternate place identifiers Source: https://developer.apple.com/documentation/applemapsserverapi/-v1-place-alternateids Get a list of alternate Place IDs given one or more Place IDs. This endpoint is available for Apple Maps Server API version 1.2 and later. ```APIDOC ## GET /v1/place/alternateIds ### Description Get a list of alternate Place IDs given one or more Place IDs. ### Method GET ### Endpoint https://maps-api.apple.com/v1/place/alternateIds ### Parameters #### Query Parameters - **ids** (string) - Required - A list of alternate Place IDs. ### Response #### Success Response (200 OK) - **AlternateIdsResponse** (object) - A list of AlternateIdsResponse results. #### Error Response (400 Bad Request) - **ErrorResponse** (object) - An ErrorResponse object that contains an error message and an array of strings that contain additional details about the error. #### Error Response (401 Unauthorized) - **ErrorResponse** (object) - An ErrorResponse object that contains an error message that indicates the Maps access token is missing or invalid, and an array of strings that contain additional details about the error. #### Error Response (500 Internal Server Error) - **ErrorResponse** (object) - An ErrorResponse object that contains a server error message and an array of strings that describe additional details about the error. ``` -------------------------------- ### Run Sample Project Source: https://developer.apple.com/documentation/applemapsserverapi/integrating-the-apple-maps-server-api-into-java-server-applications Execute these commands in the Terminal within the `server-api-examples` directory to build and run the sample application. ```bash % gradle wrapper % ./gradlew clean run ``` -------------------------------- ### DirectionsResponse.Step Object Source: https://developer.apple.com/documentation/applemapsserverapi/directionsresponse/step Represents a single step within a route, providing details like distance, duration, instructions, and transport type. ```APIDOC ## DirectionsResponse.Step Object ### Description An object that represents a step along a route. Available in Apple Maps Server API 1.2+. ### Properties - **distanceMeters** (integer) - Total distance covered by the step, in meters. - **durationSeconds** (integer) - The estimated time to traverse this step, in seconds. - **instructions** (string) - The localized instruction string for this step that you can use for display purposes. You can specify the language to receive the response in using the `lang` parameter. - **stepPathIndex** (integer) - A pointer to this step’s path. The pointer is in the form of an index into the `stepPaths` array contained in a `Route`. Step paths are self-contained which implies that the last point of a previous step path along a route is the same as the first point of the next step path. Clients are responsible for avoiding duplication when rendering the point. - **transportType** (string) - A string that indicates the transport type for this step if it’s different from the `transportType` in the route. Possible Values: `Automobile, Walking, Cycling` ``` -------------------------------- ### Place Object Source: https://developer.apple.com/documentation/applemapsserverapi/place Describes a place with properties like country, address, name, and coordinates. It also includes relationships to other objects. ```APIDOC ## Place Object ### Description An object that describes a place in terms of a variety of spatial, administrative, and qualitative properties. ### Properties - **country** (string) - The country or region of the place. - **countryCode** (string) - The 2-letter country code of the place. - **displayMapRegion** (MapRegion) - The geographic region associated with the place. This is a rectangular region on a map expressed as south-west and north-east points. Specifically south latitude, west longitude, north latitude, and east longitude. - **formattedAddressLines** (array of strings) - The address of the place, formatted using its conventions of its country or region. - **name** (string) - A place name that you can use for display purposes. - **coordinate** (Location) - The latitude and longitude of this place. - **structuredAddress** (StructuredAddress) - A `StructuredAddress` object that describes details of the place’s address. - **alternateIds** (array of strings) - A list of alternate Place IDs for the `id`. - **id** (string) - An opaque string that identifies a place. ### Relationships #### Inherited By - `SearchResponse.Place` ``` -------------------------------- ### DirectionsResponse.Step Object Source: https://developer.apple.com/documentation/applemapsserverapi/directionsresponse Represents a single step along a route within the DirectionsResponse. ```APIDOC ## DirectionsResponse.Step An object that represents a step along a route. ``` -------------------------------- ### Search Autocomplete Endpoint Source: https://developer.apple.com/documentation/applemapsserverapi/-v1-searchautocomplete This endpoint allows you to retrieve search suggestions based on a given query and an optional search location. It returns a list of potential completions, each with displayable lines and a URL to perform a more detailed search. ```APIDOC ## GET /v1/searchAutocomplete ### Description Retrieves search suggestions for a given query, optionally filtered by a search location. ### Method GET ### Endpoint /v1/searchAutocomplete ### Parameters #### Query Parameters - **q** (string) - Required - The search query string. - **searchLocation** (string) - Optional - A comma-separated string representing latitude and longitude (e.g., "37.7753881,-122.3931773"). ### Response #### Success Response (200) - **results** (array) - An array of completion objects. - **completionUrl** (string) - The URL to perform a more detailed search for this completion. - **displayLines** (array) - An array of strings representing how the completion should be displayed to the user. - **location** (object) - Optional - The geographical coordinates of the completion. - **lat** (number) - Latitude. - **lng** (number) - Longitude. - **structuredAddress** (object) - Optional - A structured representation of the completion's address. - **administrativeArea** (string) - The administrative area (e.g., state or province). - **subAdministrativeArea** (string) - The sub-administrative area. - **administrativeAreaCode** (string) - The code for the administrative area. - **locality** (string) - The city or locality. - **postCode** (string) - The postal code. - **subLocality** (string) - The sub-locality. - **thoroughfare** (string) - The street name. - **subThoroughfare** (string) - The street number. - **fullThoroughfare** (string) - The full street address including number. - **areasOfInterest** (array) - An array of area names of interest. - **dependentLocalities** (array) - An array of dependent locality names. ### Request Example ``` curl -si -H "Authorization: Bearer " \ "https://maps-api.apple.com/v1/searchAutocomplete?q=museum&searchLocation=37.7753881,-122.3931773" ``` ### Response Example ```json { "results": [ { "completionUrl": "/v1/search?q=Museums%20For%20Art", "displayLines": [ "Museums For Art", "Search Nearby" ] }, { "completionUrl": "/v1/search?q=Museum", "displayLines": [ "Museum", "Search Nearby" ] } ] } ``` ``` -------------------------------- ### SearchResponse.PaginationInfo Object Source: https://developer.apple.com/documentation/applemapsserverapi/searchresponse An object that returns a page of search responses. ```APIDOC ## SearchResponse.PaginationInfo An object that returns a page of search responses. ``` -------------------------------- ### SearchResponse.PaginationInfo Object Definition Source: https://developer.apple.com/documentation/applemapsserverapi/searchresponse/paginationinfo-data.dictionary Defines the structure of the SearchResponse.PaginationInfo object. This is a server-side definition and not typically used directly in client code. ```plaintext object SearchResponse.PaginationInfo ``` -------------------------------- ### DirectionsResponse.Step Object Definition Source: https://developer.apple.com/documentation/applemapsserverapi/directionsresponse/step This is the basic object definition for a DirectionsResponse.Step, as used in the Apple Maps Server API. ```javascript object DirectionsResponse.Step ``` -------------------------------- ### Place Object Definition Source: https://developer.apple.com/documentation/applemapsserverapi/place This snippet shows the basic definition of the Place object in the Apple Maps Server API. ```plaintext object Place ``` -------------------------------- ### SearchResponse.PaginationInfo Source: https://developer.apple.com/documentation/applemapsserverapi/searchresponse/paginationinfo-data.dictionary Represents pagination details for search results, including tokens for navigating between pages and the total number of pages and results. ```APIDOC ## SearchResponse.PaginationInfo ### Description An object that returns a page of search responses. ### Properties - **nextPageToken** (string) - An opaque string that the server uses to fetch the next page of search responses. - **prevPageToken** (string) - An opaque string that the server uses to fetch the previous page of search responses. - **totalPageCount** (number) - The total number of pages for the request. - **totalResults** (number) - The total number of results for the request. ``` -------------------------------- ### SearchResponse.Place Object Source: https://developer.apple.com/documentation/applemapsserverapi/searchresponse A structure returned by a search that describes a place. ```APIDOC ## SearchResponse.Place A structure returned by a search that describes a place. ``` -------------------------------- ### DirectionsResponse.Route Object Source: https://developer.apple.com/documentation/applemapsserverapi/directionsresponse Represents the components of a single route within the DirectionsResponse. ```APIDOC ## DirectionsResponse.Route An object that represent the components of a single route. ```