Amazon Location Service

Phase 1: Migration SDK          Phase 2: Native APIs
┌────────────────────┐          ┌────────────────────┐
│ Drop-in replacement│   →      │ Full feature access│
│ Minimal changes    │          │ Direct AWS SDK     │
│ Quick migration    │          │ No google.maps     │
└────────────────────┘          └────────────────────┘
     Hours to Days                  Days to Weeks

Are you migrating existing Google Maps code?
├─ Yes → Does Migration SDK support your Google APIs?
│        ├─ Yes → START with Phase 1 (Migration SDK)
│        │        Can transition to Phase 2 later for optimization
│        └─ No → Use Phase 2 (Native APIs)
│                 SDK won't work - go directly to native
└─ No (new app) → Use Phase 2 (Native APIs)
                  Start with native APIs from the beginning

<script>
  (g=>{var h,a,k,p="The Google Maps JavaScript API",c="google",...
    key: "YOUR_GOOGLE_API_KEY",
    v: "weekly",
  });
</script>

<script src="https://cdn.jsdelivr.net/npm/@aws/amazon-location-migration-sdk/dist/amazonLocationMigrationSDK.min.js?region=us-west-2&apiKey=YOUR_AMAZON_LOCATION_API_KEY"></script>

<script
  async
  src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&loading=async&callback=initMap&libraries=places"
></script>

<script
  async
  src="https://cdn.jsdelivr.net/npm/@aws/amazon-location-migration-sdk/dist/amazonLocationMigrationSDK.min.js?callback=initMap&region=us-west-2&apiKey=YOUR_AMAZON_LOCATION_API_KEY"
></script>

import { Loader } from "@googlemaps/js-api-loader";

const loader = new Loader({
  apiKey: "YOUR_GOOGLE_API_KEY",
  version: "weekly",
});

import { Loader } from "@aws/amazon-location-migration-sdk";

const loader = new Loader({
  apiKey: "YOUR_AMAZON_LOCATION_API_KEY",
  region: "us-west-2", // Optional, defaults to us-west-2
  version: "weekly",
});

// This code works with BOTH Google Maps and Migration SDK
let map;

async function initMap() {
  const { Map } = await google.maps.importLibrary("maps");

  map = new Map(document.getElementById("map"), {
    center: { lat: 30.268193, lng: -97.7457518 },
    zoom: 8,
  });

  // Add marker
  const { Marker } = await google.maps.importLibrary("marker");
  new Marker({
    position: { lat: 30.268193, lng: -97.7457518 },
    map: map,
  });
}

initMap();

// Import bundled client
<script src="https://cdn.jsdelivr.net/npm/@aws/amazon-location-client@1"></script>

<script>
  const API_KEY = "YOUR_API_KEY";
  const REGION = "us-west-2";

  const authHelper = amazonLocationClient.withAPIKey(API_KEY, REGION);
</script>

// 1. Create auth helper (once at app startup)
const authHelper = amazonLocationClient.withAPIKey(API_KEY, REGION);

// 2. Create service client
const client = new amazonLocationClient.GeoPlacesClient(
  authHelper.getClientConfig(),
);

// 3. Create command with parameters
const command = new amazonLocationClient.places.GeocodeCommand({
  QueryText: "123 Main St, Austin, TX",
});

// 4. Send command and await response
const response = await client.send(command);

// Google Maps (Phase 1 - Migration SDK)
const service = new google.maps.places.PlacesService(map);
service.textSearch(
  {
    query: "coffee shops in Austin",
    location: new google.maps.LatLng(30.2747, -97.7431),
  },
  (results, status) => {
    if (status === google.maps.places.PlacesServiceStatus.OK) {
      results.forEach((place) => {
        console.log(place.name, place.geometry.location);
      });
    }
  },
);

// Amazon Location (Phase 2 - Native)
const placesClient = new amazonLocationClient.GeoPlacesClient(
  authHelper.getClientConfig(),
);

const command = new amazonLocationClient.places.SearchTextCommand({
  QueryText: "coffee shops in Austin",
  BiasPosition: [-97.7431, 30.2747], // Note: [lng, lat]
  MaxResults: 10,
});

const response = await placesClient.send(command);
response.ResultItems.forEach((place) => {
  console.log(place.Title, place.Position); // [lng, lat]
});

// Google Maps (Phase 1 - Migration SDK)
const geocoder = new google.maps.Geocoder();
geocoder.geocode({ address: "Austin, TX" }, (results, status) => {
  if (status === "OK") {
    const location = results[0].geometry.location;
    console.log(location.lat(), location.lng());
  }
});

// Amazon Location (Phase 2 - Native)
const placesClient = new amazonLocationClient.GeoPlacesClient(
  authHelper.getClientConfig(),
);

const command = new amazonLocationClient.places.GeocodeCommand({
  QueryText: "Austin, TX",
  MaxResults: 1,
});

const response = await placesClient.send(command);
const [lng, lat] = response.ResultItems[0].Position;
console.log(lat, lng);

// Google Maps (Phase 1 - Migration SDK)
const directionsService = new google.maps.DirectionsService();
directionsService.route(
  {
    origin: "Austin, TX",
    destination: "Dallas, TX",
    travelMode: google.maps.TravelMode.DRIVING,
  },
  (result, status) => {
    if (status === "OK") {
      console.log(result.routes[0].legs[0].distance);
    }
  },
);

// Amazon Location (Phase 2 - Native)
const routesClient = new amazonLocationClient.GeoRoutesClient(
  authHelper.getClientConfig(),
);

const command = new amazonLocationClient.routes.CalculateRoutesCommand({
  Origin: [-97.7431, 30.2747], // Austin [lng, lat]
  Destination: [-96.797, 32.7767], // Dallas [lng, lat]
  TravelMode: "Car",
  LegGeometryFormat: "Simple", // Returns coordinate arrays for easy rendering
  LegAdditionalFeatures: ["Summary"], // Required for distance/duration
});

const response = await routesClient.send(command);
const distance =
  response.Routes[0].Legs[0].VehicleLegDetails.Summary.Overview.Distance;
console.log(distance); // meters

// Phase 1 - Migration SDK: load via the SDK's Loader, then your existing
// google.maps.geometry calls keep working unchanged.
import { Loader } from "@aws/amazon-location-migration-sdk";

const loader = new Loader({
  apiKey: "<amazon-location-api-key>",
  region: "us-east-1",
});
const { encoding } = await loader.importLibrary("geometry");

const path = [
  new google.maps.LatLng(30.2747, -97.7431),
  new google.maps.LatLng(32.7767, -96.797),
];
const encoded = encoding.encodePath(path);

// Phase 2 - Native Amazon Location with @aws/polyline
import { encodeFromLngLatArray } from "@aws/polyline";

const lngLatArray = [
  [-97.7431, 30.2747],
  [-96.797, 32.7767],
];
const encodedNative = encodeFromLngLatArray(lngLatArray);

npm install @aws/polyline

// Phase 1 - Migration SDK: load via the SDK's Loader, then your existing
// google.maps.geometry calls keep working unchanged.
import { Loader } from "@aws/amazon-location-migration-sdk";

const loader = new Loader({
  apiKey: "<amazon-location-api-key>",
  region: "us-east-1",
});
const { poly } = await loader.importLibrary("geometry");

const point = new google.maps.LatLng(30.2747, -97.7431);
const polygonPath = [
  new google.maps.LatLng(30.0, -98.0),
  new google.maps.LatLng(31.0, -98.0),
  new google.maps.LatLng(31.0, -97.0),
  new google.maps.LatLng(30.0, -97.0),
];
const polygon = new google.maps.Polygon({ paths: polygonPath });
const contains = poly.containsLocation(point, polygon);

// Phase 2 - Native Amazon Location with Turf.js
import * as turf from "@turf/turf";

const turfPoint = turf.point([-97.7431, 30.2747]); // [lng, lat]
const turfPolygon = turf.polygon([
  [
    [-98.0, 30.0],
    [-98.0, 31.0],
    [-97.0, 31.0],
    [-97.0, 30.0],
    [-98.0, 30.0], // Close the polygon
  ],
]);
const containsNative = turf.booleanPointInPolygon(turfPoint, turfPolygon);

// Google Maps (Phase 1 - Migration SDK): spherical math via the loaded
// geometry library; existing google.maps.geometry calls keep working.
const { spherical } = await google.maps.importLibrary("geometry");

const from = new google.maps.LatLng(30.2747, -97.7431);
const to = new google.maps.LatLng(32.7767, -96.797);
const distanceMeters = spherical.computeDistanceBetween(from, to);

// Amazon Location (Phase 2 - Native with Turf.js)
import * as turf from "@turf/turf";

const fromPoint = turf.point([-97.7431, 30.2747]);
const toPoint = turf.point([-96.797, 32.7767]);
const distanceMetersNative = turf.distance(fromPoint, toPoint, { units: "meters" });

npm install @turf/turf

// Google Maps (Phase 1)
const location = new google.maps.LatLng(30.2747, -97.7431); // lat, lng
console.log(location.lat(), location.lng()); // 30.2747, -97.7431

// Amazon Location (Phase 2)
const position = [-97.7431, 30.2747]; // lng, lat (GeoJSON standard)
console.log(position[1], position[0]); // 30.2747, -97.7431 (lat, lng)

const map = new google.maps.Map(document.getElementById("map"), {
  center: { lat: 30.2747, lng: -97.7431 },
  zoom: 10,
});

const marker = new google.maps.Marker({
  position: { lat: 30.2747, lng: -97.7431 },
  map: map,
  title: "Austin",
});

// Add MapLibre GL JS
import maplibregl from "maplibre-gl";
import "maplibre-gl/dist/maplibre-gl.css";

// Get Amazon Location map style
const authHelper = amazonLocationClient.withAPIKey(API_KEY, REGION);
const mapStyleUrl = `https://maps.geo.${REGION}.amazonaws.com/v2/styles/Standard/descriptor?key=${API_KEY}`;

const map = new maplibregl.Map({
  container: "map",
  style: mapStyleUrl,
  center: [-97.7431, 30.2747], // [lng, lat]
  zoom: 10,
});

const marker = new maplibregl.Marker()
  .setLngLat([-97.7431, 30.2747])
  .setPopup(new maplibregl.Popup().setText("Austin"))
  .addTo(map);

const autocomplete = new google.maps.places.Autocomplete(inputElement);

autocomplete.addListener("place_changed", () => {
  const place = autocomplete.getPlace();
  console.log(place.geometry.location);
});

const placesClient = new amazonLocationClient.GeoPlacesClient(
  authHelper.getClientConfig(),
);

let debounceTimer;
inputElement.addEventListener("input", async (e) => {
  clearTimeout(debounceTimer);

  debounceTimer = setTimeout(async () => {
    const command = new amazonLocationClient.places.AutocompleteCommand({
      QueryText: e.target.value,
      MaxResults: 5,
    });

    const response = await placesClient.send(command);
    displaySuggestions(response.ResultItems);
  }, 300);
});

// When user selects a suggestion
async function onSuggestionSelected(placeId) {
  const command = new amazonLocationClient.places.GetPlaceCommand({
    PlaceId: placeId,
  });

  const response = await placesClient.send(command);
  console.log(response.Position); // [lng, lat]
}

const service = new google.maps.places.PlacesService(map);

service.nearbySearch(
  {
    location: { lat: 30.2747, lng: -97.7431 },
    radius: 5000,
    type: "restaurant",
  },
  (results, status) => {
    if (status === google.maps.places.PlacesServiceStatus.OK) {
      results.forEach((place) => {
        addMarker(place);
      });
    }
  },
);

const placesClient = new amazonLocationClient.GeoPlacesClient(
  authHelper.getClientConfig(),
);

const command = new amazonLocationClient.places.SearchNearbyCommand({
  QueryPosition: [-97.7431, 30.2747], // [lng, lat]
  QueryRadius: 5000, // meters
  Filter: {
    IncludeCategories: ["restaurant"], // Use valid Category IDs
  },
  MaxResults: 20,
});

const response = await placesClient.send(command);
response.ResultItems.forEach((place) => {
  addMarker(place);
});

// Load both Google Maps and Migration SDK side-by-side
// Test identical operations and compare results
// Useful for validating behavior before full cutover