Amazon Location core components defined - Amazon Location Service

Amazon Location core components defined

Amazon Location Service uses GeoJSON geometries to define geographic data, such as location and boundaries, in its parameters and responses.

This section provides an introduction to the core components, terminology, and basic geometries you'll need to know when using Amazon Location Service.

Maps

Map resource

Allows you to select a map from a provider. Use the map resource to fetch map tiles that contain map data and a style descriptor to specify how features render on a map.

Basemap

Provides geographic context to your map, which are stored as vector tile layers. Tile layers include geographical context such as street names, buildings, and land use for visual reference.

Vector tile

A tile format that stores map data using vector shapes such as points, lines, and polygons. This data results in a map that can adjust to the display resolution and selectively render features in a number of ways while maintaining a small file size for optimal performance.

Supported vector file format: Mapbox Vector Tiles (MVT).

Glyph file

A binary file containing encoded Unicode characters. Used by a map renderer display labels.

Sprite file

A Portable Network Graphic (PNG) image file that contains small images, with location descriptions in a JSON file. Used by a map renderer to render icons or textures on a map.

Places

Place resource

Allows you to select a data source to support search queries. Search queries let you to search for points of interest, addresses, or coordinates. When a search query is sent to a place index resource, it's fulfilled using the resource's configured data source.

ISO 3166 country codes

Amazon Location Service Places uses the International Organization for Standardization (ISO) 3166 country codes to refer to countries or regions.

To find the code for a specific country or region, use the ISO Online Browsing Platform.

Routes

Route calculator resource

An AWS resource that enables you to estimate travel time, distance, and get directions with traffic and roadway data sourced from your chosen data provider.

Using route calculator resources, you calculate routes between an origin, a destination, and up to 25 waypoints for different modes of transportation, detours, and traffic conditions.

Route

A route contains details used when traveling along a path from the departure position, waypoint positions, and destination position.

Examples of details in a route include:

  • The distance from one position to the another.

  • The time it takes to travel from one position to the next.

  • The LineString geometry representing the path of the route.

  • Instructions for how to move to the next step between two pairs of positions

For more details on routes, see the response syntax for the CalculateRoute operation in the Amazon Location Service API reference.

Linestring geometry

An Amazon Location route consists of one or more legs represented as a LineString. A LineString is an ordered array of positions that can be used to plot a route on a map.

The following is an example of a route with one leg represented as a LineString:

  • The first position is the departure position [-122.7565, 49.0021].

  • The second position is the destination position [-122.3394, 47.6159]

[ [ [-122.7565,49.0021], [-122.3394,47.6159] ] ]
Waypoint

Waypoints are intermediate positions along a route between the departure position and destination position. The stopover order on the route follows the order that you provide the waypoint positions in the request.

The following example is a route with two waypoints. The stopover order along a route is as follows:

  • The first position is the departure position [-122.7565, 49.0021].

  • The second position on the route path is [-122.3493, 47.6205].

  • The third position on the route path is [-122.1884, 48.0936].

  • The fourth position is the destination position [-122.3394, 47.6159].

[ [ [-122.7565,49.0021], [-122.3493,47.6205], [-122.1884,48.0936], [-122.3394,47.6159] ] ]
Leg

A single leg is the journey from one position to another position. If the positions aren't located on a road, they're moved to the nearest road. The number of legs in a route is one less than the total number of positions.

A route with no waypoints consists of a single leg:

  • The start position of the leg begins at the departing position [-122.7565,49.0021].

  • The end position of the leg ends at the destination position [-122.3394, 47.6159].

Example request
POST /routes/v0/calculators/ExampleCalculator/calculate/route Content-type: application/json { "DeparturePosition": [-122.7565,49.0021], "DestinationPosition": [-122.3394, 47.6159] }
Example response
"Legs": [ { "Distance": 178.5, "DurationSeconds": 6480, "EndPosition": [-122.3394, 47.6159], "StartPosition": [-122.7565,49.0021], "Steps": [ { "Distance": 178.5, "DurationSeconds": 6480, "EndPosition": [-122.3394,47.6159], "GeometryOffset": 0, "StartPosition": [-122.7565,49.0021] } ] } ]

A route with one waypoint consists of two legs.

  • The first leg is from the departing position [-122.7565,49.0021] to the waypoint [-122.1884,48.0936].

  • The second leg is from the waypoint [-122.1884,48.0936] to the destination position [-122.3394, 47.6159].

Example request
POST /routes/v0/calculators/ExampleCalculator/calculate/route Content-type: application/json { "DeparturePosition": [-122.7565,49.0021], "DestinationPosition": [-122.3394, 47.6159], "WaypointPositions": [-122.1884,48.0936] }
Example response
"Legs": [ { "Distance": 178.5, "DurationSeconds": 6480, "EndPosition": [-122.1884,48.0936], "StartPosition": [-122.7565,49.0021], "Steps": [ { "Distance": 178.5, "DurationSeconds": 6480, "EndPosition": [-122.3394,47.6159], "GeometryOffset": 0, "StartPosition": [-122.7565,49.0021] } ] }, { "Distance": 175.5, "DurationSeconds": 6030, "EndPosition": [-122.3394, 47.6159], "StartPosition": [-122.1884,48.0936], "Steps": [ { "Distance": 175.5, "DurationSeconds": 6030, "EndPosition": [-122.3394, 47.6159], "GeometryOffset": 0, "StartPosition": [-122.1884,48.0936] } ] } ]
Step

A step is a subsection of a leg. Each step provides instructions for how to move to the next step in the leg.

Geofences

Geofence Collection

Contains zero or more geofences and is capable of geofence monitoring by emitting Entry and Exit events when requested to evaluate a device position against its geofences.

Geofence

A polygon geometry that defines a virtual boundary on a map.

Polygon geometry

An Amazon Location geofence is a virtual boundary for a geographical area and is represented as a polygon geometry.

A Polygon is an array composed of 1 or more linear rings. A linear ring is an array of 4 or more vertices, where the first and last vertex are the same to form a closed boundary. Each vertex is a 2-dimensional point of the form [longitude, latitude], where the units of longitude and latitude are degrees.

Note

Limitation — Amazon Location doesn't currently support polygons with holes, multipolygons, polygons that are wound clockwise, or that cross the antimeridian.

The first linear ring is an outer ring, describing the polygon's boundary. Subsequent linear rings may be inner or outer rings to describe holes and islands.

  • Outer rings must list their vertices in counter-clockwise order around the ring's center, where the left side is the polygon's exterior.

  • Inner rings must list their vertices in clockwise order, where the left side is the polygon's interior.

The following is an example of a single linear external ring:

[ [ [-5.716667, -15.933333], [-14.416667, -7.933333], [-12.316667, -37.066667], [-5.716667, -15.933333] ] ]

Trackers

Tracker resource

An AWS resource that receives location updates from devices. The tracker resource provides support for location queries, such as current and historic device location. Linking a tracker resource to a geofence collection evaluates location updates against all geofences in the linked geofence collection automatically.

When using Mobile Asset Tracking and Mobile Asset Management pricing plans, you use trackers to calculate the number of assets and monthly API allowance. For more information, see Amazon Location Service pricing.

Position filtering

Position filtering can help you control costs by filtering out some position updates on devices before the updates are stored or evaluated against geofences.

By default, position filtering is set to TimeBased. In TimeBased position filtering, Amazon Location evaluates every location update against linked geofence collections, but doesn't store every location update. If your update frequency is more often than 30 seconds, only one update per 30 seconds is stored for each unique device ID.

Alternately, choose DistanceBased filtering for your tracker resource. In DistanceBased filtering, Amazon Location ignores location updates if the device moved less than 30 m (98.4 ft). Amazon Location does not evaluate these updates against linked geofence collections or store them. This helps reduce costs by reducing the number of geofence evaluations and device positions to retrieve. DistanceBased filtering also reduces the jitter effect when displaying device trajectory on a map.

You can configure position filtering when you create or update tracker resources.

RFC 3339 timestamp format

Amazon Location Service Trackers uses the RFC 3339 format, which follows the International Organization for Standardization (ISO) 8601 format for dates and time.

The format is “YYYY-MM-DDThh:mm:ss.sssZ+00:00”:

  • YYYY-MM-DD — Represents the date format.

  • T — Indicates that the time values will follow.

  • hh:mm:ss.sss — Represents the time in 24-hour format.

  • Z — Indicates that the time zone used is UTC, which can be followed with deviations from the UTC time zone.

  • +00:00 — Optionally indicate deviations from the UTC time zone. For example, +01:00 indicates UTC + 1 hour.

Example

For July 2, 2020, at 12:15:20 in the afternoon, with an adjustment of an additional 1 hour to the UTC timezone.

2020-07-02T12:15:20.000Z+01:00