Amazon Location Service Maps

(1)

Amazon Location Service Maps

API Reference

API Version 2020-11-19

(2)

Amazon Location Service Maps: API Reference

Amazon's trademarks and trade dress may not be used in connection with any product or service that is not Amazon's, in any manner that is likely to cause confusion among customers, or in any manner that disparages or discredits Amazon. All other trademarks not owned by Amazon are the property of their respective owners, who may or may not be aﬃliated with, connected to, or sponsored by Amazon.

(3)

Welcome

Welcome to the Amazon Location Service Maps API Reference.

Amazon Location Maps lets you visualize location information and are the foundations of many location- based service capabilities. Amazon Location Service provides map tiles of diﬀerent styles sourced from global location data providers such as:

• Esri

• HERE Technologies

For additional information , see Data providers in the Amazon Location Service Developer Guide.

To display Amazon Location Maps in your application, add one of the service's front-end mobile of web software development kits (SDKs) to your application. For additional information on how to use map resources, see the Using maps topic in the Amazon Location Service Developer Guide. It provides deﬁnitions, tutorials, code examples, and instructions about how to integrate Amazon Location features into web or mobile apps.

NoteWhen using Amazon Location Maps, make sure to provide the appropriate data attribution and follow the terms of use for each data provider you've selected to use. For additional information, read more about Data Providers from the Amazon Location Service Developer guide.

By using Amazon Location Maps, you agree that AWS may transmit your API queries to your chosen third-party data provider for processing, which may be outside the AWS Region you are currently using. For more information, see the AWS Service Terms for Amazon Location Service.

This document was last published on March 6, 2022.

(6)

Actions

The following actions are supported:

• CreateMap (p. 3)

• DeleteMap (p. 7)

• DescribeMap (p. 9)

• GetMapGlyphs (p. 13)

• GetMapSprites (p. 16)

• GetMapStyleDescriptor (p. 19)

• GetMapTile (p. 21)

• ListMaps (p. 24)

• UpdateMap (p. 27)

(7)

CreateMap

Creates a map resource in your AWS account, which provides map tiles of diﬀerent styles sourced from global location data providers.

NoteIf your application is tracking or routing assets you use in your business, such as delivery vehicles or employees, you may only use HERE as your geolocation provider. See section 82 of the AWS service terms for more details.

Request Syntax

POST /maps/v0/maps HTTP/1.1 Content-type: application/json {

"Configuration": { "Style": "string"

},

"Description": "string", "MapName": "string", "PricingPlan": "string", "Tags": {

"string" : "string"

}}

URI Request Parameters

The request does not use any URI parameters.

Request Body

The request accepts the following data in JSON format.

Conﬁguration (p. 3)

Speciﬁes the map style selected from an available data provider.

Type: MapConﬁguration (p. 33) object Required: Yes

Description (p. 3)

An optional description for the map resource.

Type: String

Length Constraints: Minimum length of 0. Maximum length of 1000.

Required: No MapName (p. 3)

The name for the map resource.

Requirements:

(8)

Response Syntax

• Must contain only alphanumeric characters (A–Z, a–z, 0–9), hyphens (-), periods (.), and underscores (_).

• Must be a unique map resource name.

• No spaces allowed. For example, ExampleMap.

Type: String

Pattern: ^[-._\w]+$

Required: Yes PricingPlan (p. 3)

This parameter has been deprecated.

No longer used. If included, the only allowed value is RequestBasedUsage.

Type: String

Valid Values: RequestBasedUsage | MobileAssetTracking | MobileAssetManagement Required: No

Tags (p. 3)

Applies one or more tags to the map resource. A tag is a key-value pair helps manage, identify, search, and ﬁlter your resources by labelling them.

Format: "key" : "value"

Restrictions:

• Maximum 50 tags per resource

• Each resource tag must be unique with a maximum of one value.

• Maximum key length: 128 Unicode characters in UTF-8

• Maximum value length: 256 Unicode characters in UTF-8

• Can use alphanumeric characters (A–Z, a–z, 0–9), and the following characters: + - = . _ : / @.

• Cannot use "aws:" as a preﬁx for a key.

Type: String to string map

Map Entries: Minimum number of 0 items. Maximum number of 50 items.

Key Length Constraints: Minimum length of 1. Maximum length of 128.

Key Pattern: ^[a-zA-Z+-=._:/]+$

Value Length Constraints: Minimum length of 0. Maximum length of 256.

Value Pattern: ^[A-Za-z0-9 _=@:.+-/]*$

Required: No

Response Syntax

HTTP/1.1 200

Content-type: application/json

(9)

Response Elements

{

"CreateTime": number, "MapArn": "string", "MapName": "string"

}

Response Elements

If the action is successful, the service sends back an HTTP 200 response.

The following data is returned in JSON format by the service.

CreateTime (p. 4)

The timestamp for when the map resource was created in ISO 8601 format: YYYY-MM- DDThh:mm:ss.sssZ.

Type: Timestamp MapArn (p. 4)

The Amazon Resource Name (ARN) for the map resource. Used to specify a resource across all AWS.

• Format example: arn:aws:geo:region:account-id:maps/ExampleMap Type: String

Pattern: ^arn(:[a-z0-9]+([.-][a-z0-9]+)*){2}(:([a-z0-9]+([.-][a-z0-9]+)*)?) {2}:([^/].*)?$

MapName (p. 4)

The name of the map resource.

Type: String

Pattern: ^[-._\w]+$

Errors

For information about the errors that are common to all actions, see Common Errors (p. 38).

AccessDeniedException

The request was denied because of insuﬃcient access or permissions. Check with an administrator to verify your permissions.

HTTP Status Code: 403 ConﬂictException

The request was unsuccessful because of a conﬂict.

HTTP Status Code: 409 InternalServerException

The request has failed to process because of an unknown server error, exception, or failure.

(10)

See Also

HTTP Status Code: 500 ThrottlingException

The request was denied because of request throttling.

HTTP Status Code: 429 ValidationException

The input failed to meet the constraints speciﬁed by the AWS service.

HTTP Status Code: 400

DeleteMap

Deletes a map resource from your AWS account.

NoteThis operation deletes the resource permanently. If the map is being used in an application, the map may not render.

Request Syntax

DELETE /maps/v0/maps/MapName HTTP/1.1

URI Request Parameters

The request uses the following URI parameters.

MapName (p. 7)

The name of the map resource to be deleted.

Pattern: ^[-._\w]+$

Required: Yes

Request Body

The request does not have a request body.

Response Syntax

HTTP/1.1 200

Response Elements

If the action is successful, the service sends back an HTTP 200 response with an empty HTTP body.

Errors

(12)

See Also

HTTP Status Code: 500 ResourceNotFoundException

The resource that you've entered was not found in your AWS account.

DescribeMap

Retrieves the map resource details.

Request Syntax

GET /maps/v0/maps/MapName HTTP/1.1

URI Request Parameters

MapName (p. 9)

The name of the map resource.

Pattern: ^[-._\w]+$

Required: Yes

Request Body

Response Syntax

HTTP/1.1 200

Content-type: application/json {

"Configuration": { "Style": "string"

},

"CreateTime": number, "DataSource": "string", "Description": "string", "MapArn": "string", "MapName": "string", "PricingPlan": "string", "Tags": {

"string" : "string"

},

"UpdateTime": number }

Response Elements

(14)

Response Elements

Conﬁguration (p. 9)

Speciﬁes the map tile style selected from a partner data provider.

Type: MapConﬁguration (p. 33) object CreateTime (p. 9)

Type: Timestamp DataSource (p. 9)

Speciﬁes the data provider for the associated map tiles.

Type: String Description (p. 9)

The optional description for the map resource.

Type: String

MapArn (p. 9)

The Amazon Resource Name (ARN) for the map resource. Used to specify a resource across all AWS.

MapName (p. 9)

The map style selected from an available provider.

Type: String

Pattern: ^[-._\w]+$

PricingPlan (p. 9)

No longer used. Always returns RequestBasedUsage.

Type: String

Valid Values: RequestBasedUsage | MobileAssetTracking | MobileAssetManagement Tags (p. 9)

Tags associated with the map resource.

Type: String to string map

Map Entries: Minimum number of 0 items. Maximum number of 50 items.

(15)

Errors

Key Length Constraints: Minimum length of 1. Maximum length of 128.

Key Pattern: ^[a-zA-Z+-=._:/]+$

Value Length Constraints: Minimum length of 0. Maximum length of 256.

Value Pattern: ^[A-Za-z0-9 _=@:.+-/]*$

UpdateTime (p. 9)

The timestamp for when the map resource was last update in ISO 8601 format: YYYY-MM- DDThh:mm:ss.sssZ.

Type: Timestamp

Errors

GetMapGlyphs

Retrieves glyphs used to display labels on a map.

Request Syntax

GET /maps/v0/maps/MapName/glyphs/FontStack/FontUnicodeRange HTTP/1.1

URI Request Parameters

FontStack (p. 13)

A comma-separated list of fonts to load glyphs from in order of preference. For example, Noto Sans Regular, Arial Unicode.

Valid fonts stacks for Esri styles:

• VectorEsriDarkGrayCanvas – Ubuntu Medium Italic | Ubuntu Medium | Ubuntu Italic | Ubuntu Regular | Ubuntu Bold

• VectorEsriLightGrayCanvas – Ubuntu Italic | Ubuntu Regular | Ubuntu Light | Ubuntu Bold

• VectorEsriTopographic – Noto Sans Italic | Noto Sans Regular | Noto Sans Bold | Noto Serif Regular | Roboto Condensed Light Italic

• VectorEsriStreets – Arial Regular | Arial Italic | Arial Bold

• VectorEsriNavigation – Arial Regular | Arial Italic | Arial Bold Valid font stacks for HERE Technologies styles:

• VectorHereBerlin – Fira GO Regular | Fira GO Bold Required: Yes

FontUnicodeRange (p. 13)

A Unicode range of characters to download glyphs for. Each response will contain 256 characters.

For example, 0–255 includes all characters from range U+0000 to 00FF. Must be aligned to multiples of 256.

Pattern: ^[0-9]+-[0-9]+\.pbf$

Required: Yes MapName (p. 13)

The map resource associated with the glyph ﬁle.

Pattern: ^[-._\w]+$

Required: Yes

Request Body

(18)

Response Syntax

HTTP/1.1 200

Content-Type: ContentType Blob

Response Elements

The response returns the following HTTP headers.

ContentType (p. 14)

The map glyph content type. For example, application/octet-stream.

The response returns the following as the HTTP body.

Blob (p. 14)

The blob's content type.

Errors

(19)

See Also

GetMapSprites

Retrieves the sprite sheet corresponding to a map resource. The sprite sheet is a PNG image paired with a JSON document describing the oﬀsets of individual icons that will be displayed on a rendered map.

Request Syntax

GET /maps/v0/maps/MapName/sprites/FileName HTTP/1.1

URI Request Parameters

FileName (p. 16)

The name of the sprite ﬁle. Use the following ﬁle names for the sprite sheet:

• sprites.png

• [email protected] for high pixel density displays

For the JSON document contain image oﬀsets. Use the following ﬁle names:

• sprites.json

• [email protected] for high pixel density displays Pattern: ^sprites(@2x)?\.(png|json)$

Required: Yes MapName (p. 16)

The map resource associated with the sprite ﬁle.

Pattern: ^[-._\w]+$

Required: Yes

Request Body

Response Syntax

HTTP/1.1 200

Response Elements

(21)

Errors

The content type of the sprite sheet and oﬀsets. For example, the sprite sheet content type is image/png, and the sprite oﬀset JSON document is application/json.

Blob (p. 16)

Contains the body of the sprite sheet or JSON oﬀset ﬁle.

Errors

GetMapStyleDescriptor

Retrieves the map style descriptor from a map resource.

The style descriptor contains speciﬁcations on how features render on a map. For example, what data to display, what order to display the data in, and the style for the data. Style descriptors follow the Mapbox Style Speciﬁcation.

Request Syntax

GET /maps/v0/maps/MapName/style-descriptor HTTP/1.1

URI Request Parameters

MapName (p. 19)

The map resource to retrieve the style descriptor from.

Pattern: ^[-._\w]+$

Required: Yes

Request Body

Response Syntax

HTTP/1.1 200

Response Elements

The style descriptor's content type. For example, application/json.

Blob (p. 19)

Contains the body of the style descriptor.

(24)

Errors

GetMapTile

Retrieves a vector data tile from the map resource. Map tiles are used by clients to render a map. they're addressed using a grid arrangement with an X coordinate, Y coordinate, and Z (zoom) level.

The origin (0, 0) is the top left of the map. Increasing the zoom level by 1 doubles both the X and Y dimensions, so a tile containing data for the entire world at (0/0/0) will be split into 4 tiles at zoom 1 (1/0/0, 1/0/1, 1/1/0, 1/1/1).

Request Syntax

GET /maps/v0/maps/MapName/tiles/Z/X/Y HTTP/1.1

URI Request Parameters

MapName (p. 21)

The map resource to retrieve the map tiles from.

Pattern: ^[-._\w]+$

Required: Yes X (p. 21)

The X axis value for the map tile.

Pattern: \d+

Required: Yes Y (p. 21)

The Y axis value for the map tile.

Pattern: \d+

Required: Yes Z (p. 21)

The zoom value for the map tile.

Pattern: \d+

Required: Yes

Request Body

Response Syntax

HTTP/1.1 200

(26)

Response Elements

The map tile's content type. For example, application/vnd.mapbox-vector-tile.

Blob (p. 21)

Contains Mapbox Vector Tile (MVT) data.

Errors

ListMaps

Lists map resources in your AWS account.

Request Syntax

POST /maps/v0/list-maps HTTP/1.1 Content-type: application/json {

"MaxResults": number, "NextToken": "string"

}

URI Request Parameters

The request does not use any URI parameters.

Request Body

MaxResults (p. 24)

An optional limit for the number of resources returned in a single call.

Default value: 100 Type: Integer

Valid Range: Minimum value of 1. Maximum value of 100.

Required: No NextToken (p. 24)

The pagination token specifying which page of results to return in the response. If no token is provided, the default page is the ﬁrst page.

Default value: null Type: String

Required: No

Response Syntax

HTTP/1.1 200

Content-type: application/json {

"Entries": [ {

(29)

Response Elements

"CreateTime": number, "DataSource": "string", "Description": "string", "MapName": "string", "PricingPlan": "string", "UpdateTime": number }

],

"NextToken": "string"

}

Response Elements

Entries (p. 24)

Contains a list of maps in your AWS account

Type: Array of ListMapsResponseEntry (p. 31) objects NextToken (p. 24)

A pagination token indicating there are additional pages available. You can use the token in a following request to fetch the next set of results.

Type: String

Errors

(30)

See Also

UpdateMap

Updates the speciﬁed properties of a given map resource.

Request Syntax

PATCH /maps/v0/maps/MapName HTTP/1.1 Content-type: application/json {

"Description": "string", "PricingPlan": "string"

}

URI Request Parameters

MapName (p. 27)

The name of the map resource to update.

Pattern: ^[-._\w]+$

Required: Yes

Request Body

Description (p. 27)

Updates the description for the map resource.

Type: String

Required: No PricingPlan (p. 27)

No longer used. If included, the only allowed value is RequestBasedUsage.

Type: String

Response Syntax

HTTP/1.1 200

(32)

Response Elements

Content-type: application/json { "MapArn": "string",

"MapName": "string", "UpdateTime": number }

Response Elements

MapArn (p. 27)

The Amazon Resource Name (ARN) of the updated map resource. Used to specify a resource across AWS.

MapName (p. 27)

The name of the updated map resource.

Type: String

Pattern: ^[-._\w]+$

UpdateTime (p. 27)

The timestamp for when the map resource was last updated in ISO 8601 format: YYYY-MM- DDThh:mm:ss.sssZ.

Type: Timestamp

Errors

(33)

See Also

ResourceNotFoundException

Data Types

The Amazon Location Service Maps API contains several data types that various actions use. This section describes each data type in detail.

Note

The order of each element in a data type structure is not guaranteed. Applications should not assume a particular order.

The following data types are supported:

• ListMapsResponseEntry (p. 31)

• MapConﬁguration (p. 33)

• ValidationExceptionField (p. 35)

(35)

ListMapsResponseEntry

Contains details of an existing map resource in your AWS account.

MapConﬁguration

Speciﬁes the map tile style selected from an available provider.

ValidationExceptionField

The input failed to meet the constraints specified by the AWS service in a specified field.

Common Parameters

The following list contains the parameters that all actions use for signing Signature Version 4 requests with a query string. Any action-speciﬁc parameters are listed in the topic for that action. For more information about Signature Version 4, see Signature Version 4 Signing Process in the Amazon Web Services General Reference.

Action

The action to be performed.

Type: string Required: Yes Version

The API version that the request is written for, expressed in the format YYYY-MM-DD.

Type: string Required: Yes X-Amz-Algorithm

The hash algorithm that you used to create the request signature.

Condition: Specify this parameter when you include authentication information in a query string instead of in the HTTP authorization header.

Type: string

Valid Values: AWS4-HMAC-SHA256 Required: Conditional

X-Amz-Credential

The credential scope value, which is a string that includes your access key, the date, the region you are targeting, the service you are requesting, and a termination string ("aws4_request"). The value is expressed in the following format: access_key/YYYYMMDD/region/service/aws4_request.

For more information, see Task 2: Create a String to Sign for Signature Version 4 in the Amazon Web Services General Reference.

Type: string

Required: Conditional X-Amz-Date

The date that is used to create the signature. The format must be ISO 8601 basic format (YYYYMMDD'T'HHMMSS'Z'). For example, the following date time is a valid X-Amz-Date value:

20120325T120000Z.

Condition: X-Amz-Date is optional for all requests; it can be used to override the date used for signing requests. If the Date header is speciﬁed in the ISO 8601 basic format, X-Amz-Date is

(41)

not required. When X-Amz-Date is used, it always overrides the value of the Date header. For more information, see Handling Dates in Signature Version 4 in the Amazon Web Services General Reference.

Type: string

Required: Conditional X-Amz-Security-Token

The temporary security token that was obtained through a call to AWS Security Token Service (AWS STS). For a list of services that support temporary security credentials from AWS Security Token Service, go to AWS Services That Work with IAM in the IAM User Guide.

Condition: If you're using temporary security credentials from the AWS Security Token Service, you must include the security token.

Type: string

Required: Conditional X-Amz-Signature

Speciﬁes the hex-encoded signature that was calculated from the string to sign and the derived signing key.

Type: string

Required: Conditional X-Amz-SignedHeaders

Speciﬁes all the HTTP headers that were included as part of the canonical request. For more information about specifying signed headers, see Task 1: Create a Canonical Request For Signature Version 4 in the Amazon Web Services General Reference.

Type: string

Required: Conditional

(42)

Common Errors

This section lists the errors common to the API actions of all AWS services. For errors speciﬁc to an API action for this service, see the topic for that API action.

You do not have suﬃcient access to perform this action.

HTTP Status Code: 400 IncompleteSignature

The request signature does not conform to AWS standards.

HTTP Status Code: 400 InternalFailure

The request processing has failed because of an unknown error, exception or failure.

HTTP Status Code: 500 InvalidAction

The action or operation requested is invalid. Verify that the action is typed correctly.

HTTP Status Code: 400 InvalidClientTokenId

The X.509 certiﬁcate or AWS access key ID provided does not exist in our records.

HTTP Status Code: 403 InvalidParameterCombination

Parameters that must not be used together were used together.

HTTP Status Code: 400 InvalidParameterValue

An invalid or out-of-range value was supplied for the input parameter.

HTTP Status Code: 400 InvalidQueryParameter

The AWS query string is malformed or does not adhere to AWS standards.

HTTP Status Code: 400 MalformedQueryString

The query string contains a syntax error.

HTTP Status Code: 404 MissingAction

The request is missing an action or a required parameter.

(43)

MissingAuthenticationToken

The request must contain either a valid (registered) AWS access key ID or X.509 certiﬁcate.

HTTP Status Code: 403 MissingParameter

A required parameter for the speciﬁed action is not supplied.

HTTP Status Code: 400 NotAuthorized

You do not have permission to perform this action.

HTTP Status Code: 400 OptInRequired

The AWS access key ID needs a subscription for the service.

HTTP Status Code: 403 RequestExpired

The request reached the service more than 15 minutes after the date stamp on the request or more than 15 minutes after the request expiration date (such as for pre-signed URLs), or the date stamp on the request is more than 15 minutes in the future.

HTTP Status Code: 400 ServiceUnavailable

The request has failed due to a temporary failure of the server.

The request was denied due to request throttling.

HTTP Status Code: 400 ValidationError

The input fails to satisfy the constraints speciﬁed by an AWS service.

Amazon Location Service Maps

Amazon Location Service Maps

API Reference

API Version 2020-11-19

Amazon Location Service Maps: API Reference

Table of Contents

Welcome

Actions

CreateMap

Request Syntax

URI Request Parameters

Request Body

Response Syntax

Response Elements

Errors

See Also

DeleteMap

Request Syntax

URI Request Parameters

Request Body

Response Syntax

Response Elements

Errors

See Also

DescribeMap

Request Syntax

URI Request Parameters

Request Body

Response Syntax

Response Elements

Errors

See Also

GetMapGlyphs

Request Syntax

URI Request Parameters

Request Body

Response Syntax

Response Elements

Errors

See Also

GetMapSprites

Request Syntax

URI Request Parameters

Request Body

Response Syntax

Response Elements

Errors

See Also

GetMapStyleDescriptor

Request Syntax

URI Request Parameters

Request Body

Response Syntax

Response Elements

Errors

See Also

GetMapTile

Request Syntax

URI Request Parameters

Request Body

Response Syntax

Response Elements

Errors

See Also

ListMaps

Request Syntax

URI Request Parameters

Request Body

Response Syntax

Response Elements

Errors

See Also

UpdateMap

Request Syntax

URI Request Parameters

Request Body

Response Syntax

Response Elements

Errors

See Also