📚 AWS Location Service Reference v0 (legacy) & v2 (standalone)

AWS Location Service Reference

Pilih operation di sidebar kiri untuk lihat detail endpoint, request body, response shape, dan perbandingan v0 ↔ v2.

Default provider di ap-southeast-1 = GrabMaps. Dokumentasi ini fokus untuk integrasi API.

Region Caveats — ap-southeast-1 (GrabMaps)
  • Map styles: hanya Standard & Monochrome (Hybrid/Satellite ditolak)
  • Live Traffic parameter: ditolak. DepartureTime tetap honored via pola traffic historis per jam
  • Avoid options yang valid: TollRoads, Ferries, ControlledAccessHighways (DirtRoads/Tunnels/UTurns ditolak)
  • Waypoints: PassThrough tidak didukung — omit field-nya
  • Routes return Tolls dan MajorRoadLabels — tapi AWS jarang populate field ini di SEA
  • Suggest tidak return Position by default — tambah AdditionalFeatures: ['Core']
  • GetPlace: Contacts, OpeningHours, Brand, FoodTypes jarang populated di SEA

Operation

⏳ Coming Soon

Operation ini belum tersedia di API key kamu untuk region ap-southeast-1.

Dokumentasi detail akan ditambahkan setelah AWS rilis action ini di region kamu. Sementara, cek alternatif yang sudah available di sidebar (dot hijau).

Routes V2 / CalculateRoutes

CalculateRoutes

Hitung rute dari Origin ke Destination, dengan opsi waypoints, mode kendaraan, hindari toll/ferry, dan turn-by-turn instructions.

POSThttps://routes.geo.{region}.amazonaws.com/v2/routes?key=...
Request Syntax
{
  "Origin": [ number, number ],
  "Destination": [ number, number ],
  "Waypoints": [ { "Position": [ number, number ], "StopDuration": number } ],
  "TravelMode": "Car" | "Scooter" | "Pedestrian" | "Truck",
  "TravelStepType": "Default" | "TurnByTurn",
  "LegGeometryFormat": "Simple" | "FlexiblePolyline",
  "InstructionsMeasurementSystem": "Metric" | "Imperial",
  "Locale": "string",
  "Avoid": {
    "TollRoads": boolean,
    "Ferries": boolean,
    "ControlledAccessHighways": boolean,
    "DirtRoads": boolean,
    "TruckRoadTypes": [ "string" ],
    "Areas": [ { "Geometry": { "Polygon": [...] } } ]
  },
  "DepartureTime": "string",
  "ArrivalTime": "string",
  "OptimizeRoutingFor": "FastestRoute" | "ShortestRoute",
  "MaxAlternatives": 0..6
}
Request Parameters
FieldTypeRequiredNote
Origin[lng, lat]YESStarting point
Destination[lng, lat]YESEnd point
Waypointsarray—Max 23 (excluding Origin & Destination)
TravelModeenum—Default: Car. v0→v2 mapping: Motorcycle→Scooter, Walking→Pedestrian
LegGeometryFormatenum—Simple = LineString array, FlexiblePolyline = encoded
Avoid.TollRoadsboolean—Not supported for Pedestrian
DepartureTimeISO 8601—Mutually exclusive with ArrivalTime
OptimizeRoutingForenum—Default: FastestRoute
MaxAlternatives0–6—Request alternative routes. Response Routes[] = primary + alternatives. Actual count depends on geography (kadang AWS return lebih sedikit dari yang diminta).
TravelStepTypeenum—Set ke TurnByTurn untuk dapat full turn-by-turn instructions (VehicleLegDetails.TravelSteps[] dengan Type/SteeringDirection/CurrentRoad/NextRoad).
⚠️ Region caveats (ap-southeast-1): Avoid.DirtRoads, Avoid.Tunnels, Avoid.UTurns ditolak dengan FieldValidationFailed. Hanya TollRoads, Ferries, ControlledAccessHighways yang valid. Live Traffic parameter juga ditolak — DepartureTime akan honored lewat pola traffic historis per jam.
Field Rules
Required
Origin Destination
Dua-duanya wajib. Format [lng, lat] valid.
Mutually exclusive
DepartureTime XOR ArrivalTime
Pilih salah satu — kapan mau berangkat ATAU kapan harus tiba. Default = sekarang.
Avoid options
TollRoads Ferries ControlledAccessHighways DirtRoads
Boleh dikombinasi semua. ⚠️ TollRoads=true tidak boleh untuk TravelMode Pedestrian (error 400).
Independent
TravelMode LegGeometryFormat Locale OptimizeRoutingFor
Common Errors
StatusTriggerAWS Message
400Tanpa Origin atau Destination"Origin/Destination is required"
400Avoid.TollRoads dengan TravelMode: Pedestrian"TollRoads not supported for Pedestrian"
400Waypoints > 23"...less than or equal to 23"
400Kirim DepartureTime + ArrivalTime bareng"Only one of DepartureTime/ArrivalTime allowed"
400Origin/Destination tidak bisa di-reach (mis. tengah laut)"No route found"
Response Syntax
{
  "PricingBucket": "string",
  "LegGeometryFormat": "string",
  "Notices": [...],
  "Routes": [
    {
      "Summary": { "Distance": number, "Duration": number },
      "Legs": [
        {
          "Distance": number,
          "Duration": number,
          "Geometry": { "LineString": [ [lng, lat], ... ] },
          "TravelMode": "string",
          "Type": "Vehicle" | "Pedestrian" | "Ferry",
          "VehicleLegDetails": {
            "TravelSteps": [ { "Distance": number, "Duration": number, "Instruction": "string" } ]
          }
        }
      ]
    }
  ]
}
Response Fields
FieldTypeNote
Routes[0].Summary.DistancenumberMeters (not km like v0)
Routes[0].Summary.DurationnumberSeconds (previously DurationSeconds)
Routes[0].Legs[].Geometry.LineStringarrayArray of [lng, lat] for MapLibre LineString
Routes[0].Legs[].TypeenumVehicle / Pedestrian / Ferry
Routes[0].Legs[].VehicleLegDetails.TravelStepsarrayTurn-by-turn instructions (when TravelStepType=TurnByTurn)
Try it Live
🔒 Proxy ada 2 varian — pilih sesuai use case:
• /api/v2/routes/calculate = native passthrough — body langsung shape v2 (Origin/Destination/Waypoints[].Position). Try-It panel ini pakai endpoint ini.
• /api/routes/calculate = v0-shape adapter — terima body shape v0 lama (DeparturePosition/DestinationPosition/WaypointPositions) lalu translate ke v2 internally. Dipakai home page untuk backward compat.
 Presets
Request Body VALID
POSThttps://routes.geo.ap-southeast-1.amazonaws.com/v2/routes
VIA/api/v2/routes/calculate
Response — idle —
Klik Send Request.
POST/routes/v0/calculators/{Calc}/calculate/route?key=...
Request Body
{
  "DeparturePosition": [106.84, -6.20],
  "DestinationPosition": [106.85, -6.24],
  "WaypointPositions": [[106.846, -6.21]],
  "TravelMode": "Car",
  "DistanceUnit": "Kilometers",
  "IncludeLegGeometry": true,
  "AvoidTolls": true,
  "DepartNow": true
}
Response
{
  "Summary": { "Distance": 5.2, "DurationSeconds": 720 },
  "Legs": [{ "Distance": 5.2, "DurationSeconds": 720,
             "Geometry": { "LineString": [[106.84,-6.20], ...] } }]
}
Differences from v2:
  • DeparturePosition → Origin, DestinationPosition → Destination
  • WaypointPositions: [[lng,lat]] → Waypoints: [{ Position: [lng,lat] }]
  • AvoidTolls: bool → Avoid: { TollRoads: bool } (nested)
  • TravelMode: Motorcycle → Scooter, Walking → Pedestrian
  • Distance v0 dalam kilometer, v2 meter
  • DurationSeconds → Duration
  • Response wrapper: v0 langsung Summary/Legs, v2 ada Routes[0] array
Routes V2 / CalculateRouteMatrix

CalculateRouteMatrix

Hitung jarak & waktu untuk semua kombinasi origin × destination — efisien untuk "find nearest" use case.

POSThttps://routes.geo.{region}.amazonaws.com/v2/route-matrix?key=...
Request Syntax
{
  "Origins": [ { "Position": [ number, number ] } ],
  "Destinations": [ { "Position": [ number, number ] } ],
  "TravelMode": "Car" | "Scooter" | "Pedestrian" | "Truck",
  "RoutingBoundary": {
    "Unbounded": true,
    "Geometry": { "AutoCircle": { "Margin": number, "MaxRadius": number } }
  },
  "Avoid": {
    "TollRoads": boolean,
    "Ferries": boolean
  },
  "DepartureTime": "string",
  "OptimizeRoutingFor": "FastestRoute" | "ShortestRoute"
}
Request Parameters
FieldTypeRequiredNote
OriginsarrayYESArray of { Position: [lng,lat] }
DestinationsarrayYESArray of { Position: [lng,lat] }
RoutingBoundaryobjectYESWAJIB di v2! { Unbounded: true } untuk perilaku v0.
TravelModeenum—Default: Car
Avoid.TollRoadsboolean—Not allowed for Pedestrian
Field Rules
Required
Origins Destinations RoutingBoundary
Tiga-tiganya wajib. Beda dari v0 yang gak butuh RoutingBoundary.
Cell limit
Origins.length × Destinations.length ≤ 700
Max 700 sel per request. Mis. 7×100 atau 35×20. Pisah jadi multiple request kalau lebih.
Common Errors
StatusTriggerAWS Message
400Tanpa RoutingBoundary"RoutingBoundary is required"
400Origins × Destinations > 700"Too many cells: max 700"
400Position kosong di salah satu Origins/Destinations"Position is required"
Response Syntax
{
  "PricingBucket": "string",
  "RouteMatrix": [
    [
      { "Distance": number, "Duration": number, "Error": null }
    ]
  ],
  "ErrorCount": number
}
Response Fields
FieldTypeNote
RouteMatrix[i][j].DistancenumberMeter (v0: km)
RouteMatrix[i][j].DurationnumberDetik (v0: DurationSeconds)
RouteMatrix[i][j].Errorobject|nullPer-cell error (e.g. unreachable). null if OK.
Try it Live
🔒 Aman — routing lewat /api/routes/matrix (Laravel proxy).
🔒 Aman — proxy /api/routes/matrix sekarang pakai v2 adapter di backend: terima payload v0-shape (DeparturePositions/DestinationPositions) lalu translate ke v2 (/v2/route-matrix) + adapt response balik ke v0-shape (Distance dalam km, DurationSeconds). Untuk native v2, lihat tab v2 atau panggil AWS langsung dengan API Key.
 Presets
Request Body VALID
POSThttps://routes.geo.ap-southeast-1.amazonaws.com/v2/route-matrix
VIA/api/routes/matrix
Response — idle —
Klik Send Request.
POST/routes/v0/calculators/{Calc}/calculate/route-matrix?key=...
Request Body
{
  "DeparturePositions": [[106.84, -6.20]],
  "DestinationPositions": [[106.85,-6.24], [106.86,-6.25]],
  "TravelMode": "Car",
  "DistanceUnit": "Kilometers"
}
Response (km, DurationSeconds)
{
  "RouteMatrix": [[
    { "Distance": 1.2, "DurationSeconds": 240 },
    { "Distance": 2.5, "DurationSeconds": 480 }
  ]]
}
Differences from v2:
  • DeparturePositions: [[lng,lat]] → Origins: [{ Position: [lng,lat] }]
  • DestinationPositions: [[lng,lat]] → Destinations: [{ Position: [lng,lat] }]
  • v2 wajib RoutingBoundary (v0 tidak)
  • Distance: v0 km → v2 meter
  • DurationSeconds → Duration
Routes V2 / CalculateIsolines

CalculateIsolines v2 only

Polygon area "reachable within X minutes" atau "within Y km" dari satu titik. Cocok untuk visualisasi service coverage.

⏳ Coming Soon Not available in region ap-southeast-1. Action not listed in AWS Console permissions. Wait for AWS rollout or use the workaround below.
POST/v2/isolines?key=...

Request body

{
  "Origin": [106.84, -6.20],
  "TravelMode": "Car",
  "Thresholds": {
    "Time": [300, 600, 900]
  },
  "OptimizeIsolineFor": "FastestRoute"
}

Bisa juga pakai Thresholds.Distance (meter) atau kedua-duanya.

Response

{
  "Isolines": [{
    "TimeThreshold": 300,
    "Geometries": [{
      "Polygon": [[ [106.83,-6.19], ... ]]
    }]
  }]
}
💡 Use case: visualize "stops reachable within 10 minutes on foot" with polygon overlay on MapLibre.
Routes V2 / OptimizeWaypoints

OptimizeWaypoints v2 only

TSP solver — kasih AWS list of waypoints, dia kembalikan urutan optimal (ngirit jarak/waktu).

⏳ Coming Soon Not available in region ap-southeast-1. For this feature, implement nearest-neighbor TSP yourself in JS or use a library.
POST/v2/optimize-waypoints?key=...

Request body

{
  "Origin": [106.84, -6.20],
  "Destination": [106.92, -6.30],
  "Waypoints": [
    { "Id": "stop1", "Position": [106.85,-6.21] },
    { "Id": "stop2", "Position": [106.90,-6.22] },
    { "Id": "stop3", "Position": [106.87,-6.25] }
  ],
  "TravelMode": "Car",
  "OptimizeSequencingFor": "FastestRoute"
}

Response

{
  "OptimizedWaypoints": [
    { "Id": "stop1", "Position": [106.85,-6.21] },
    { "Id": "stop3", "Position": [106.87,-6.25] },
    { "Id": "stop2", "Position": [106.90,-6.22] }
  ],
  "Distance": 12500,
  "Duration": 1850
}
✅ Sebelumnya kamu harus implement TSP / nearest-neighbor sendiri di JS. Sekarang AWS yang hitungkan.
Routes V2 / SnapToRoads

SnapToRoads v2 only

Snap GPS trace yang noisy ke jalan terdekat. Berguna untuk clean trip log GPS dari kendaraan.

⏳ Coming Soon Not available in region ap-southeast-1. Not yet rolled out for GrabMaps provider.
POST/v2/snap-to-roads?key=...

Request body

{
  "TracePoints": [
    { "Position": [106.840, -6.200] },
    { "Position": [106.842, -6.201] },
    { "Position": [106.845, -6.203] }
  ],
  "TravelMode": "Car",
  "SnappedGeometryFormat": "Simple"
}

Response

{
  "SnappedGeometry": {
    "LineString": [[106.840,-6.200], [106.843,-6.201], ...]
  },
  "SnappedTracePoints": [
    { "OriginalPosition": [106.840,-6.200], "SnappedPosition": [106.840,-6.200] }
  ]
}
💡 Pair with ride-hailing trip recording to get clean trip lines (without GPS-noise zigzags).
Maps V2 / GetStyleDescriptor

GetStyleDescriptor

Return MapLibre style spec JSON. URL ini langsung ditaroh di property style waktu inisialisasi MapLibre map.

GEThttps://maps.geo.{region}.amazonaws.com/v2/styles/{Style}/descriptor?key=...
Query Parameters
ParamValuesNote
{Style}PATHenum Standard | Monochrome | Hybrid | SatelliteIn ap-southeast-1: only Standard & Monochrome (GrabMaps provider)
keyREQstringAPI key
color-schemeenum Light | DarkOnly for Standard / Monochrome
political-viewstring ISO-3IDN, MYS, ARG, MAR, etc.
Field Rules
Style + Color compatibility
Standard + Light/Dark ✓
Monochrome + Light/Dark ✓
Hybrid/Satellite + color-scheme ❌
Raster styles (Hybrid/Satellite) don't accept color-scheme — sending it returns error 400.
Common Errors
StatusTriggerAWS Message
400Style not available in region (e.g. Satellite in ap-southeast-1)"Satellite is not a supported map style"
400color-scheme used on Hybrid/Satellite"color-scheme not applicable"
403API Key lacks geo-maps:GetStyleDescriptor"explicit deny"
Response (JSON)
{
  "version": 8,
  "name": "Standard",
  "sources": {
    "tiles": { "type": "vector", "tiles": [ "https://maps.geo.../v2/tiles/Standard/Default/Default/{z}/{x}/{y}?key=..." ] }
  },
  "sprite": "https://maps.geo.../v2/sprites/Standard/Default/Default",
  "glyphs": "https://maps.geo.../v2/glyphs/Standard/{fontstack}/{range}?key=...",
  "layers": [ ... ]
}

Style descriptor is a complete MapLibre recipe — it contains URLs for GetTile / GetGlyphs / GetSprites. MapLibre auto-fetches all three.

Try it Live
💡 Pick style + color + political-view → the MapLibre map below auto re-renders with the new style descriptor.
 Presets
URL
GET/maps/v0/maps/{MapName}/style-descriptor?key=...
Differences from v2:
  • Pakai {MapName} custom resource (harus dibuat dulu di Console)
  • Tidak ada color-scheme / political-view param
  • Provider lock per resource — gak bisa switch style runtime
Maps V2 / GetTile

GetTile

Vector / raster tile per koordinat z/x/y. URL pattern ini ada di field tiles dalam style descriptor — biasanya gak perlu di-call manual.

GEThttps://maps.geo.{region}.amazonaws.com/v2/tiles/{Style}/{ColorScheme}/{Variant}/{z}/{x}/{y}?key=...
Path / Query Parameters
ParamTypeNote
{Style}pathStandard | Monochrome | Hybrid | Satellite
{ColorScheme}pathLight | Dark | Default
{Variant}pathDefault (for now)
{z}/{x}/{y}path intTile coordinate (z 0-22, x/y per zoom level)
keyqueryAPI key
Common Errors
gt; 2^z - 1
StatusTriggerNote
400z/x/y out of valid rangeE.g. y Mis. y > 2^z - 1
404Tile not available in this areaE.g. coordinate outside provider coverage
403API Key lacks geo-maps:GetTilePermission missing
Response Content-Type
StyleContent-TypeFormat
Standard / Monochromeapplication/x-protobufVector tile (PBF) — rendered by MapLibre client-side
Hybrid / Satelliteimage/png atau image/jpegRaster tile, rendered as-is
Try it Live
💡 Use the z/x/y picker to view a specific tile. Vector tile (PBF) cannot be previewed directly — use MapLibre to render it.
z/x/y
URL

⬆️ Klik Open untuk download tile. Vector PBF (Standard/Monochrome) terlihat sebagai binary file. Raster (Satellite/Hybrid) terlihat sebagai gambar.

GET/maps/v0/maps/{MapName}/tiles/{z}/{x}/{y}?key=...
Differences from v2:
  • Path lebih sederhana: {MapName}/tiles/{z}/{x}/{y}
  • Tidak ada Style/ColorScheme/Variant — provider locked di resource
Maps V2 / GetGlyphs

GetGlyphs

Font glyphs (PBF) untuk text rendering di vector tiles. Auto-fetched oleh MapLibre, gak perlu di-call manual.

GEThttps://maps.geo.{region}.amazonaws.com/v2/glyphs/{Style}/{fontstack}/{range}?key=...
Path Parameters
ParamTypeNote
{Style}pathStandard | Monochrome
{fontstack}pathNama font (mis. Noto Sans Regular) — URL-encoded
{range}pathUnicode range, 256 chars per chunk: 0-255, 256-511, dst.
Response Content-Type

application/x-protobuf — binary PBF berisi font glyphs. Di-decode sama MapLibre untuk render label di map.

Common Errors
StatusTriggerNote
404Fontstack not availableSee available fonts in the style descriptor
400Invalid rangeMax range usually up to 65279 (basic Unicode)
403Permission missinggeo-maps:GetGlyphs gak di-grant
Try it Live
💡 Glyphs PBF cannot be previewed directly. Shown here: URL builder + open button to download the file.
Style Font Range
URL
GET/maps/v0/maps/{MapName}/glyphs/{fontstack}/{range}?key=...
Differences from v2:
  • Path: {MapName}/glyphs/{fontstack}/{range} (tanpa Style)
  • Font set tergantung MapName resource
Maps V2 / GetSprites

GetSprites

Sprite sheet (PNG + JSON) untuk icon point-of-interest di map. Auto-fetched oleh MapLibre.

GEThttps://maps.geo.{region}.amazonaws.com/v2/sprites/{Style}/{ColorScheme}/{Variant}/{file}?key=...
Path Parameters
ParamTypeNote
{Style}pathStandard | Monochrome
{ColorScheme}pathLight | Dark | Default
{Variant}pathDefault
{file}pathsprites.json | sprites.png | sprites@2x.json | sprites@2x.png
Response Content-Type
FileContent-TypeNote
sprites.jsonapplication/jsonManifest: coordinates & size of each icon in the sheet
sprites.pngimage/pngSheet image — all icons in one PNG
sprites@2x.pngimage/png@2x version for retina display
Try it Live
💡 PNG sprites can be previewed directly. JSON manifest can be fetched to inspect structure.
Style Color File
URL
Sprite preview
GET/maps/v0/maps/{MapName}/sprites?key=...
Differences from v2:
  • Path: {MapName}/sprites (tanpa Style/Color/Variant/file split)
  • v0 punya endpoint terpisah untuk JSON vs PNG (mis. /sprites?json=true)
  • Sprite set lock per provider
Maps V2 / GetStaticMap

GetStaticMap v2 only

Render map jadi gambar PNG/JPEG single. Cocok untuk thumbnail, preview di card, email, atau social sharing.

⏳ Coming Soon Not available in region ap-southeast-1. Maps Actions in Console only has GetTile. Workaround: screenshot from MapLibre canvas.
GET/v2/static-map?key=...&...

Query parameters

Param Type Note
CenterREQ lng,lat Map center
ZoomREQ number 0-22
WidthREQ number Pixel
HeightREQ number Pixel
Style — Standard | Monochrome | Hybrid | Satellite
FileFormat — png | jpeg
Pins array Optional marker overlay

Example

GET/v2/static-map?key=...&Center=106.84,-6.20&Zoom=14&Width=600&Height=400&Style=Standard

Hasil: gambar PNG 600×400 pusat di Sudirman zoom 14.

Places V2 / SearchText

SearchText

Pencarian Place (POI / alamat / area) berbasis free-form text. Cocok untuk search bar dengan tombol "Search". Mendukung bias position, filter geografis (BoundingBox/Circle/Country), dan filter kategori.

POSThttps://places.geo.{region}.amazonaws.com/v2/search-text?key=...
Request Syntax
{
                            "QueryText": "string",
                            "QueryId": "string",
                            "MaxResults": number,
                            "BiasPosition": [ number, number ],
                            "Filter": {
                                "BoundingBox": [ number, number, number, number ],
                                "Circle": {
                                "Center": [ number, number ],
                                "Radius": number
                                },
                                "IncludeCountries": [ "string" ]
                            },
                            "AdditionalFeatures": [ "string" ],
                            "Language": "string",
                            "PoliticalView": "string",
                            "IntendedUse": "string",
                            "NextToken": "string"
                            }
Request Parameters
Field Type Required Note
QueryText string YES* Free-form keyword (1-200 char). *Required: one of QueryText or QueryId.
QueryId string — Alternative: ID from a previous Suggest result
MaxResults number — 1–20, default 20
BiasPosition [lng, lat] — Bias ranking + reference for the Distance field. Exactly 1 of BiasPosition / Filter.BoundingBox / Filter.Circle.
📌 Use this if you need Distance — Filter.Circle/BoundingBox don't trigger Distance in ap-southeast-1.
Filter.BoundingBox [w, s, e, n] — Limit results to a box (west, south, east, north)
Filter.Circle object — Center: [lng,lat], Radius: meter (max 50000)
Filter.IncludeCountries array<string> — ISO-3 country codes, e.g. ["IDN"]
AdditionalFeatures array<string> — Contact | TimeZone | Phonemes | Access
Language string — BCP 47 (e.g. id, en)
PoliticalView string — ISO-3 country code (e.g. IDN)
IntendedUse string — SingleUse (default) | Storage
NextToken string — Pagination cursor
Field Rules — yang bisa & tidak bisa di-combo
Required (one-of)
QueryText OR QueryId
One of these must be in the body. Both can be sent but AWS picks based on internal priority.
Mutually exclusive (exactly one)
BiasPosition XOR Filter.BoundingBox XOR Filter.Circle
Sending 2 or more = 400 error "Exactly one of...". Sending none → no spatial bias (global results).
💡 Trade-off:
· BiasPosition → ranking-bias + Distance field in response
· Filter.Circle / BoundingBox → hard geographic cut-off but no Distance (empirical in ap-southeast-1)
Can be combined
Filter.IncludeCountries + BiasPosition/Circle/BoundingBox
IncludeCountries is an additive filter (AND), not exclusive — can be combined with any spatial filter.
Independent (use freely)
MaxResults Language PoliticalView AdditionalFeatures IntendedUse NextToken
These fields have no conflict constraints with each other. Use any combination or none at all.
Common Errors & Validation
Status Trigger AWS Message
400 2+ of BiasPosition / Filter.BoundingBox / Filter.Circle sent together "Exactly one of the following fields must be set: BiasPosition, Filter.BoundingBox, Filter.Circle."
400 No QueryText and no QueryId "Either QueryText or QueryId is required."
400 MaxResults > 20 "Member must have value less than or equal to 20"
400 Filter.Circle.Radius > 50000 "Member must have value less than or equal to 50000"
400 Wrong coordinate format (e.g. [lat, lng] instead of [lng, lat]) Weird / empty result — AWS doesn't validate ranges, coords are accepted as-is
400 Filter.IncludeCountries not ISO-3 (e.g. "Indonesia" or "ID") "Validation failed: country code must be 3 letters"
403 API Key lacks action geo-places:SearchText "User is not authorized to access this resource with an explicit deny"
403 API Key wrong or missing ?key= "The security token included in the request is invalid"
429 Rate limit exceeded (default 50 TPS) "Rate exceeded" — implement retry with backoff
Response Syntax
{
                            "PricingBucket": "string",
                            "NextToken": "string",
                            "ResultItems": [
                                {
                                "PlaceId": "string",
                                "PlaceType": "string",
                                "Title": "string",
                                "Address": {
                                    "Label": "string",
                                    "Country": { "Code2": "string", "Name": "string" },
                                    "Region": { "Code": "string", "Name": "string" },
                                    "Locality": "string",
                                    "PostalCode": "string"
                                },
                                "Position": [ number, number ],
                                "MapView": [ number, number, number, number ],
                                "Distance": number,
                                "Categories": [ { "Id": "string", "Name": "string", "Primary": boolean } ],
                                "TimeZone": { "Name": "string", "OffsetSeconds": number }
                                }
                            ]
                            }
Response Fields
Field Type Note
ResultItems[].PlaceId string Unique AWS ID — use with GetPlace to fetch full detail
ResultItems[].PlaceType string PointOfInterest | Address | Street | District | Region | etc.
ResultItems[].Title string Main display name
ResultItems[].Position [lng, lat] Center coordinate of the place
ResultItems[].Distance number Meters from reference point.
⚠️ Empirical in ap-southeast-1: this field only appears when the request uses BiasPosition. When using Filter.Circle or Filter.BoundingBox, the Distance field is absent from the response.
Workaround: compute Haversine in JS from Position to the origin.
ResultItems[].Address object Structured address (label + components)
ResultItems[].MapView [w,s,e,n] Bounding box for fitting the map
ResultItems[].Categories array Kategori AWS (mis. transit_station_bus)
Try it Live
 Presets
Request Body VALID
POST https://places.geo.ap-southeast-1.amazonaws.com/v2/search-text?key=*** (canonical AWS URL — reference)
Response — idle —
Klik Send Request di atas untuk lihat live response dari AWS.
POSThttps://places.geo.{region}.amazonaws.com/places/v0/indexes/{IndexName}/search/text?key=...
Request Body
{
  "Text": "halte TJ",
  "BiasPosition": [106.84, -6.20],
  "MaxResults": 10,
  "FilterCountries": ["IDN"]
}
Response Body
{
  "Summary": { "Text": "halte TJ", "MaxResults": 10, "ResultBBox": [...] },
  "Results": [
    {
      "Place": {
        "Label": "Halte TJ Halimun, Jakarta",
        "Geometry": { "Point": [106.85, -6.24] },
        "Country": "IDN",
        "AddressNumber": "5"
      },
      "Distance": 850.42
    }
  ]
}
Differences from v2:
  • Field Text → QueryText
  • FilterCountries → Filter.IncludeCountries
  • Response: Results[].Place.Geometry.Point → ResultItems[].Position
  • MaxResults max 10 (v2: 20)
  • Must create PlaceIndex resource first in AWS Console
Places V2 / Suggest

Suggest

Type-ahead autocomplete — return Place hits + Query refinement. Pakai untuk dropdown live di search bar.

POSThttps://places.geo.{region}.amazonaws.com/v2/suggest?key=...
Request Syntax
{
  "QueryText": "string",
  "MaxResults": number,
  "BiasPosition": [ number, number ],
  "Filter": {
    "BoundingBox": [ number, number, number, number ],
    "Circle": { "Center": [ number, number ], "Radius": number },
    "IncludeCountries": [ "string" ]
  },
  "AdditionalFeatures": [ "string" ],
  "Language": "string",
  "PoliticalView": "string",
  "MaxQueryRefinements": number,
  "IntendedUse": "string"
}
Request Parameters
FieldTypeRequiredNote
QueryTextstringYES1–200 char. Partial keyword OK (autocomplete).
MaxResultsnumber—1–10, default 5
BiasPosition[lng, lat]—Exactly 1 dari Bias / Filter.Circle / Filter.BoundingBox.
Filter.Circleobject—Center: [lng,lat], Radius: meter (max 50000)
Filter.BoundingBox[w,s,e,n]—west, south, east, north
Filter.IncludeCountriesarray—ISO-3 codes
MaxQueryRefinementsnumber—Max items with SuggestResultItemType=Query
Languagestring—BCP 47 (e.g. id)
AdditionalFeaturesarray—Valid: Core, TimeZone, Phonemes. Tip: tambah "Core" untuk unlock field Position di response — tanpa ini Suggest gak return koordinat (jadi distance ke marker user gak bisa dihitung client-side).
💡 Penting untuk autocomplete dengan distance: response Suggest tidak include Position by default. Kirim "AdditionalFeatures": ["Core"] untuk dapat lat/lng tiap suggestion — supaya bisa compute distance dari current marker/map center langsung di client.
Field Rules
Required
QueryText
Wajib ada QueryText (min 1 karakter). Suggest tidak menerima QueryId seperti SearchText.
Mutually exclusive
BiasPosition XOR Filter.BoundingBox XOR Filter.Circle
Pakai 2+ = error 400.
Response filter (client-side)
SuggestResultItemType
Filter SuggestResultItemType === "Place" untuk actual place; "Query" = refinement keyword saja.
Independent
MaxResults Language PoliticalView MaxQueryRefinements
Common Errors
StatusTriggerAWS Message
4002+ spatial filter"Exactly one of..."
400Empty QueryText"QueryText: Member must have length greater than or equal to 1"
400MaxResults > 10"...less than or equal to 10"
403Action geo-places:Suggest tidak di-grant"explicit deny"
Response Syntax
{
  "PricingBucket": "string",
  "ResultItems": [
    {
      "Title": "string",
      "SuggestResultItemType": "Place" | "Query",
      "Highlights": { "Title": [...] },
      "Place": {
        "PlaceId": "string",
        "PlaceType": "string",
        "Address": { "Label": "string" },
        "Position": [ number, number ],
        "Distance": number,
        "Categories": [ ... ]
      },
      "Query": { "QueryId": "string", "QueryType": "string" }
    }
  ]
}
Response Fields
FieldTypeNote
SuggestResultItemTypeenumPlace = actual hit, Query = refinement keyword
Place.Position[lng,lat]Only for SuggestResultItemType=Place
Place.DistancenumberMeters (only when using BiasPosition)
Highlights.TitlearrayRange index for highlighting matched keywords
Query.QueryIdstringPass to SearchText as QueryId for full search
Try it Live
🔒 Aman — routing lewat /api/places/suggestions (Laravel proxy). API key di server.
 Presets
Request Body VALID
POSThttps://places.geo.ap-southeast-1.amazonaws.com/v2/suggest
VIA/api/places/suggestions
Response — idle —
Klik Send Request di atas.
POST/places/v0/indexes/{Idx}/search/suggestions?key=...
Request Body
{
  "Text": "halte tj",
  "BiasPosition": [106.84, -6.20],
  "MaxResults": 5,
  "FilterCountries": ["IDN"]
}
Response
{
  "Summary": { "Text": "halte tj" },
  "Results": [
    { "Text": "Halte Transjakarta Halimun", "PlaceId": "AQABA..." }
  ]
}
Differences from v2:
  • Text → QueryText
  • FilterCountries → Filter.IncludeCountries
  • Results[].Text → ResultItems[].Title
  • v0 tidak return Position di Suggest — harus call GetPlace
Places V2 / ReverseGeocode

ReverseGeocode

Koordinat → alamat terdekat.

POSThttps://places.geo.{region}.amazonaws.com/v2/reverse-geocode?key=...
Request Syntax
{
  "QueryPosition": [ number, number ],
  "QueryRadius": number,
  "MaxResults": number,
  "Filter": {
    "IncludePlaceTypes": [ "string" ]
  },
  "AdditionalFeatures": [ "string" ],
  "Language": "string",
  "PoliticalView": "string",
  "IntendedUse": "string"
}
Request Parameters
FieldTypeRequiredNote
QueryPosition[lng, lat]YESCoordinate point to reverse-geocode
QueryRadiusnumber—Search radius (meters), default 0 (exact point)
MaxResultsnumber—1–4, default 1
Filter.IncludePlaceTypesarray—Locality | Street | PointAddress | Block | dst.
AdditionalFeaturesarray—TimeZone | Access
Languagestring—BCP 47
Field Rules
Required
QueryPosition
Wajib koordinat [lng, lat] valid (lng ±180, lat ±90).
Filter PlaceType
Filter.IncludePlaceTypes
Batasi tipe hasil — mis. cuma Street atau PointAddress aja, tanpa Locality/District.
Common Errors
StatusTriggerAWS Message
400Tanpa QueryPosition"QueryPosition is required"
400Format [lat, lng] (terbalik)Hasil aneh — AWS treat sebagai [lng, lat]
400MaxResults > 4"...less than or equal to 4"
Response Syntax
{
  "PricingBucket": "string",
  "ResultItems": [
    {
      "PlaceId": "string",
      "PlaceType": "string",
      "Title": "string",
      "Address": {
        "Label": "string",
        "Country": { "Code2": "string", "Name": "string" },
        "Region": { "Code": "string", "Name": "string" },
        "PostalCode": "string"
      },
      "Position": [ number, number ],
      "Distance": number,
      "MapView": [ number, number, number, number ]
    }
  ]
}
Response Fields
FieldTypeNote
ResultItems[].TitlestringShort location name
ResultItems[].Address.LabelstringFull formatted address
ResultItems[].DistancenumberMeters from QueryPosition
ResultItems[].PlaceTypestringLocality, District, Street, PointAddress, dst.
Try it Live
🔒 Aman — routing lewat /api/places/reverse (Laravel proxy).
 Presets
Request Body VALID
POSThttps://places.geo.ap-southeast-1.amazonaws.com/v2/reverse-geocode
VIA/api/places/reverse
Response — idle —
Klik Send Request.
POST/places/v0/indexes/{Idx}/search/position?key=...
Request Body
{
  "Position": [106.84, -6.20],
  "MaxResults": 1
}
Differences from v2:
  • Position → QueryPosition
  • Tidak ada Filter.IncludePlaceTypes di v0
  • Wajib bikin PlaceIndex resource dulu
Places V2 / GetPlace

GetPlace

Detail lengkap Place by PlaceId (dari hasil Search/Suggest sebelumnya).

GEThttps://places.geo.{region}.amazonaws.com/v2/place/{PlaceId}?key=...&...
Query Parameters
ParamTypeRequiredNote
{PlaceId}pathYESPath segment (URL-encoded). From SearchText/Suggest.
keyqueryYESAPI key
additional-featuresquery—Comma-separated: TimeZone,Contact,Hours,Phonemes,Access
languagequery—BCP 47 (e.g. id, en)
political-viewquery—ISO-3 country code
intended-usequery—SingleUse | Storage
Field Rules
Required
PlaceId (path)
Wajib di URL path. PlaceId valid time-bounded ~1 jam dari saat di-issue Search/Suggest.
Additional Features
TimeZone Contact Hours Phonemes Access
Opsional, comma-separated. Tambah cost per feature. Beberapa region cuma support TimeZone.
Common Errors
StatusTriggerAWS Message
404PlaceId tidak ditemukan / expired"Place not found"
400additional-features berisi value yang gak disupport region"Unsupported AdditionalFeatures..."
403API Key tidak punya geo-places:GetPlace"explicit deny"
Response Syntax
{
  "PlaceId": "string",
  "PlaceType": "string",
  "Title": "string",
  "Address": {
    "Label": "string",
    "Country": { "Code2": "string", "Name": "string" },
    "Region": { "Code": "string", "Name": "string" },
    "Locality": "string",
    "PostalCode": "string"
  },
  "Position": [ number, number ],
  "MapView": [ number, number, number, number ],
  "Categories": [ { "Id": "string", "Name": "string", "Primary": boolean } ],
  "Contacts": {
    "Phones": [ { "Value": "string" } ],
    "Websites": [ { "Value": "string" } ]
  },
  "OpeningHours": [
    { "Display": [ "string" ], "OpenNow": boolean }
  ],
  "TimeZone": { "Name": "string", "Offset": "string", "OffsetSeconds": number }
}
Try it Live
💡 Dapat PlaceId dulu dari Try it Live SearchText/Suggest, copy hasil ResultItems[0].PlaceId, paste ke sini.
Query Parameters
GEThttps://places.geo.ap-southeast-1.amazonaws.com/v2/place/<PlaceId>
VIA/api/places/<PlaceId>
Response — idle —
Masukkan PlaceId lalu klik Send Request.
GET/places/v0/indexes/{Idx}/places/{PlaceId}?key=...
Differences from v2:
  • Path beda: /places/v0/indexes/{Idx}/places/{PlaceId}
  • Tidak ada additional-features param di v0
  • Response shape lebih simple, tanpa OpeningHours, Contacts, TimeZone
Places V2 / Autocomplete

Autocomplete v2 only

Type-ahead khusus untuk alamat (street, address number, postal code) — bukan untuk POI.

POST/v2/autocomplete?key=...

Request body

{
  "QueryText": "Jl. Sudirman",
  "BiasPosition": [106.84, -6.20],
  "Filter": {
    "IncludeCountries": ["IDN"],
    "IncludePlaceTypes": ["Street", "PointAddress"]
  },
  "MaxResults": 5,
  "Language": "id"
}

Response (does NOT return Position)

{
  "ResultItems": [{
    "Title": "Jl. Jenderal Sudirman, Jakarta",
    "PlaceId": "AQAB...",
    "Address": { "Label": "..." },
    "Distance": 1250,
    "Highlights": { ... }
  }]
}
⚠️ Does not return Position — must call GetPlace per item if you need coordinates. For finding POIs, Suggest is more efficient (returns Position directly).
⏳ Coming Soon Not available in region ap-southeast-1 at the moment. Check AWS Console for available actions.

IncludePlaceTypes valid values

Locality | PostalCode | Intersection | Street | PointAddress | InterpolatedAddress

PointOfInterest is not valid in Autocomplete — use SearchText / SearchNearby.

Places V2 / Geocode

Geocode v2 only

Alamat terstruktur (street, city, postal) → koordinat. Lebih akurat dari SearchText untuk address lookup karena input-nya sudah parsed.

⏳ Coming Soon Not available in region ap-southeast-1. Workaround: use SearchText with structured QueryText.
POST/v2/geocode?key=...

Request body

{
  "QueryComponents": {
    "Country": "IDN",
    "Region": "Jakarta",
    "Locality": "Jakarta Selatan",
    "Street": "Jl. Sudirman",
    "AddressNumber": "1",
    "PostalCode": "10220"
  },
  "MaxResults": 1
}

Response

{
  "ResultItems": [{
    "Title": "Jl. Sudirman 1, Jakarta",
    "Position": [106.823, -6.224],
    "Address": { ... },
    "MatchScores": { "Overall": 0.95 }
  }]
}
💡 Use this when you already have field-by-field address (e.g. from a form input). For free-text search, use SearchText.
Places V2 / SearchNearby

SearchNearby v2 only

Find POI dalam radius dari satu titik, opsional filter by category. Tidak butuh QueryText — cuma "tunjukin yang dekat tipe X".

⏳ Coming Soon Not available in region ap-southeast-1. Workaround: use SearchText with Filter.Circle + category keyword in QueryText.
POST/v2/search-nearby?key=...

Request body

{
  "QueryPosition": [106.84, -6.20],
  "QueryRadius": 1000,
  "Filter": {
    "IncludeCategories": ["transit_station_bus"]
  },
  "MaxResults": 20,
  "Language": "id"
}

Response

{
  "ResultItems": [{
    "Title": "Halte Transjakarta Halimun",
    "PlaceId": "AQAB...",
    "Position": [106.85, -6.24],
    "Distance": 850,
    "Categories": [{ "Id": "transit_station_bus", "Primary": true }]
  }]
}
✅ Untuk use case "halte terdekat" ini paling direct: 1 API call, sorted by distance, gak perlu QueryText. Prasyaratnya kamu tau ID kategori (mis. transit_station_bus).

Notes

  • Max QueryRadius = 50,000 m (50 km)
  • Max MaxResults = 20
General / Overview

Overview v0 vs v2

Dua generation API yang masih jalan paralel. v2 = standalone mode (recommended), v0 = legacy resource-based.

Aspek v0 Legacy v2 Standalone
Setup AWS Console Must create Map / PlaceIndex / RouteCalculator first Not needed — works immediately
Hostname maps.geo.{region}.amazonaws.com (shared) Per service: maps.geo, places.geo, routes.geo
Path version /{service}/v0/... /v2/...
Provider Lock per resource Auto-picked per region
Status ⚠️ Maintenance only ✅ Active development
Rekomendasi: Project baru pakai v2. Project existing tetap aman di v0 sampai AWS announce deprecation.
General / Authentication

Authentication

Dua-duanya support API Key (recommended frontend) atau AWS SigV4 (backend).

API Key in URL

?key=v1.public.eyJq...

Resource ARN (per service)

Service v0 v2
Maps arn:aws:geo:...:map/{Name} arn:aws:geo-maps:...::provider/default
Places arn:aws:geo:...:place-index/{Name} arn:aws:geo-places:...::provider/default
Routes arn:aws:geo:...:route-calculator/{Name} arn:aws:geo-routes:...::provider/default
⚠️ Saat bikin API Key di AWS Console, centang actions per service yang dibutuhkan. Action yang gak dicentang akan return 403 Forbidden (explicit deny).
General / Quotas & Limits

Quotas & Limits

Limit per request untuk API Location v2.

Operation Param Limit
SearchText MaxResults 20
Suggest MaxResults 10
ReverseGeocode MaxResults 4
SearchNearby MaxResults 20
All Search Filter.Circle.Radius 50,000 m
CalculateRoutes Waypoints 23
CalculateRouteMatrix Origins × Destinations 700 cells
Rate limit (default) — 50 TPS / account (Places)

Lengkap: Service Quotas

General / Migration Guide

Migration v0 → v2

Checklist 3-step untuk pindahin code dari v0 (resource-based) ke v2 (standalone).

1. Maps

  • Hapus dependency ke AWS_MAP_NAME
  • Ganti URL style ke /v2/styles/Standard/descriptor
  • Tambah API Key actions: geo-maps:*

2. Places

  • Hapus AWS_MAP_PLACE (PlaceIndex)
  • Endpoint: /places/v0/indexes/.../search/text → /v2/search-text
  • Body: Text → QueryText, FilterCountries → Filter.IncludeCountries
  • Response: Results → ResultItems, Place.Geometry.Point → Position

3. Routes

  • Hapus AWS_MAP_ROUTE (RouteCalculator)
  • Endpoint ke /v2/routes & /v2/route-matrix
  • Body: DeparturePosition → Origin, WaypointPositions → Waypoints: [{Position}]
  • TravelMode: Motorcycle/Walking → Scooter/Pedestrian
  • Distance v0 (km) → v2 (meter), DurationSeconds → Duration
  • Matrix: tambah RoutingBoundary: {Unbounded: true}
💡 Test on a separate endpoint first (e.g. /transjakarta-test) before migrating production code.