Amazon Location Service: New APIs and Features for Enhanced Location-Based Applications

by Ceyda Kamalı

Nov 22, 2024

15 min read

SHARE ON SOCIAL MEDIA

Hello! In this article, I'm going to talk about the new features that Amazon Location Service has introduced. With 7 new APIs and 10 enhanced APIs for Routes, Places, and Maps, developing location-based applications is now easier and more accessible than ever. Also, in this article, I will show how we can use some of the APIs of Amazon Location Service with a small demo.

Before we start learning about these features, let's take a brief look at what Amazon Location Service does. Amazon Location Service is an AWS service that provides developers with maps, routes and places data for location-based applications. This service facilitates location-based app development by providing functionality such as map display, route optimization, and finding nearby places.

For example, a shopping app can help users find nearby stores and see store information. A food ordering app could show users the location of restaurants and let them see which restaurants are serving food.

So, now that we know basically what Amazon Location Service does, let's take a look at the details of the new APIs and updated APIs offered by Amazon Location Service and the advantages it offers to developers!

Amazon Location Service API Updates: New Features and Improvements

1- Routes API: Saving Time and Distance on the Road

Amazon Location Service's Routes API has enabled significant improvements in route planning and customization. With these features, users can now create more efficient routes. Here are some of the new highlights:

Calculatelsolines: You can specify service areas within a certain distance or travel time. This feature is especially useful for logistics and delivery applications.
OptimizeWaypoints: By arranging the waypoints on the routes in the most efficient order, you can save time or distance. This enables finding the shortest route efficiently.
Calculate Toll Costs: By calculating highway tolls, you can estimate total costs. It is a great convenience especially for those who use toll roads while traveling.
SnapToRoads: By pinning GPS data to the road, you can guarantee that the points are on the right road. This feature allows drivers and the app to be guided more accurately.

As an example, a food delivery app can reduce delivery time and lower fuel costs by optimizing the routes of its drivers. By using real-time traffic data, the fastest and most cost-effective route can be suggested.

2- Maps API: Professionalism in Map Design

The Maps API takes a big step forward in map display, offering more professional map designs. With these features, you can integrate maps much faster and more efficiently.

GetStaticMap: You can integrate static maps into applications without the need for dynamic maps. This is especially ideal for apps that don't need to stream data and want a simpler map display. For example, a hotel booking app might provide a static map to show the user the location of the hotel. When you just want to show the user the location of the hotel, there is no need for dynamic maps that require a constant stream of data. This results in a solution that loads faster and uses fewer resources.
GetTile: By downloading a specific tile (square) from map sets, you can show the desired point on the map faster. For example, a navigation app will load only the currently visible area on the map as the user moves. This feature allows you to react quickly on dynamic maps and allows users to have a seamless experience on the map.
GetStyleDescriptor: You can query map styles in detail, allowing for enhanced customization of the map's design. For example, a travel app can change its style to highlight tourist areas or restaurants on the map. This way, the map is not only functional, but also visually appealing to the user.

So, what is a static and dynamic map? Let's take a look at it.

Static and dynamic maps provide distinct approaches to map representation. A static map is a type of map that is presented as a fixed image and does not interact with the user. For example, a map with the address of a restaurant only shows the location of the restaurant. The user cannot make any changes or interact with this map.

Dynamic maps, on the other hand, are the types of maps where users can interact with the map and the map is constantly updated. For example, when using a navigation app, the map is constantly moving and new information and directions are added as the user moves along the map. Dynamic maps allow users to zoom in on the map, search for new paths or navigate around the map, providing a more interactive and enhanced experience.

To take an example, in a restaurant finder app, users can search for restaurants in the neighborhood on a map. Thanks to the GetStaticMap property, the location of each restaurant can be shown visually in a simple way. If the user selects a restaurant, the map is dynamically loaded with the GetTile property, and driving directions can be started to direct the user to the location of the restaurant. Also, with GetStyleDescriptor you can customize the map style to highlight the restaurants, for example by using a theme that highlights the tourist areas to enrich the user experience.

3- Places API: Finding Nearby Places

Improvements to the Places API allow users to find places around them in much more detail. This feature is especially useful for apps that use location-based searches.

SearchNearby and Autocomplete: Enables users to easily find nearby places. For example, when a user searches for “restaurants nearby” in a food ordering app, the app can automatically list restaurants in the vicinity.
Business Hours and Contact Information: Details such as business hours and contact information are now more easily accessible. This feature improves the experience, especially by quickly providing location information that users need.

To take an example, let's take a food ordering app. When the user searches for “restaurants nearby”, the app can not only list the restaurants in the vicinity, but also quickly display their opening hours and contact information. This way, the user knows which restaurants are open and how to get in touch.

So, let's do a demo to better understand what we have learned and explore the possibilities that Amazon Location Service offers. This demo will show more concretely how we can use the APIs we have learned.

Amazon Location Service offers 2 ways to validate API calls:

1- AWS API Authentication (AWS Sigv4): This authentication method is the strongest in terms of security and is typically used on the server side.

2- API Keys: This is an easier and more practical authentication method for mobile applications. It is ideal for applications that do not require authentication of your users

So, now that we've learned how to validate API calls, let's move on to the first step of our demo

Step 1: Generate API Key

First, I will create an API key for my application, which I will use to access the Amazon Location APIs. You can easily create API keys through the AWS CLI. You can also manage your keys through the AWS Management Console.

I run the following command to generate the API key using AWS CLI:

  ~ REGION=eu-west-1
  ~ KEYNAME=geo-key-cey


  ~ aws location create-key --region ${REGION} --key-name ${KEYNAME} --restrictions \
  > AllowActions="geo-routes:*","geo-places:*","geo-maps:*",\
  > AllowResources="arn:aws:geo-routes:${REGION}::provider/default",\
  > "arn:aws:geo-places:${REGION}::provider/default",\
  > "arn:aws:geo-maps:${REGION}::provider/default" \
  > --no-expiry

As a result of this command, you will have created an API key via Amazon Location Service. This key can be used in Amazon Location Service API calls with the specified AllowActions and AllowResources restrictions. This key is used for authentication in the application.

When this command runs successfully, you should see JSON output like this

  {
    "Key": "v1.public.eyJ...cy",       
    "KeyArn": "arn:aws:geo:eu-west-1:account-id:api-key/geo-key-cey", 
    "KeyName": "geo-key-cey",         
    "CreateTime": "2024-11-12T18:23:13.353000+00:00" 
  }

Step 2: Obtain Geographic Coordinates for Colosseum, Rome, Italy

Now, let's see how we can get the geographic coordinates of the Colosseum, a well-known place in Italy, using Amazon Location Service's GeoCode API.

The GeoCode API returns the geographic coordinates of a given address. That is, you enter an address and the API gives you the latitude and longitude of that address. This functionality is particularly valuable for map-based applications or location-based services. For example, if you want to show your users' locations on a map or determine the closest locations to them, this is where the GeoCode API comes in.

Now, let's see how to use this API by entering Colosseum's address.

  ~ curl --slient -X "POST" "https://places.geo.${REGION}.amazonaws.com/v2/geocode?key=<API_KEY>" \
  > -d '{ "QueryText": "Colosseum, Roma, İtalya" }'

When we make this query, we get a JSON response with address details and geographic coordinates for the Colosseum. The response includes details such as the exact address where the Colosseum is located, country details and geographic position (latitude and longitude). Here is our response value returned according to the query above:

  "ResultItems": [
    {
      "PlaceId": "AQA8S...S",
      "PlaceType": "PointOfInterest",
      "Title": "Colosseo",
      "Address": {
        "Label": "Colosseo, Piazza del Colosseo, 00184 Roma RM, Italia",
        "Country": {
          "Code2": "IT", 
          "Code3": "ITA", 
          "Name": "Italia"
        },
        "Region": {
          "Name": "Lazio"
        },
        "SubRegion": {
          "Code": "RM", 
          "Name": "Roma"
        },
        "Locality": "Roma",
        "District": "Celio",
        "PostalCode": "00184",
        "Street": "Piazza del Colosseo",
        "StreetComponents": [
          {
            "BaseName": "Colosseo", 
            "Type": "Piazza del",
            "TypePlacement": "BeforeBaseName",
            "TypeSeparator": " ",
            "Language": "it"
          }
        ]
        "Position": [12.49337, 41.88989],
        "Categories": [
          {
            "Id": "historical_monument",
            "Name": "Historical Monument",
            "LocalizedName": "Monumento storico",
            "Primary": True
          },
          {
            "Id": "landmark-attraction",
            "Name": "Landmark-Attraction",
            "LocalizedName": "Punto di riferimento o attrazione",
            "Primary": False
          },
          {
            "Id": "bicycle_and_bicycle_accessories_shop",
            "Name": "Bicycle and Bicycle Accessories Shop",
            "LocalizedName": "Vendita biciclett...",
            "Primary": False
          },
        ],
        "MatchScores": {
          "Overall": 1,
          "Components": {
            "Title": 1,
            "Address": {
              "Country": 1,
              "Locality": 1
            }
          }
        }
      }
    }
  ]

This response is the JSON response you received for “Colosseo” from Amazon Location Service's GeoCode API. The JSON response provides detailed information about the location you queried and contains the following data:

PlaceId: A unique ID for this place, denoted as "PointOfInterest".
Title: Gives a description of the place with the title “Colosseo”.
*Address: The full address of the Colosseo is provided:
- Label: Full address formatted as “Colosseo, Piazza del Colosseo, 00184 Roma RM, Italia”.
- It contains more detailed regional information such asCountry, Region, SubRegion (for example, Lazio region and Rome subregion).
- PostalCode: “00184”, indicating the postal code.
- Street: “Piazza del Colosseo” provides the street name.
- StreetComponents: Contains a detailed description of the street “Piazza del Colosseo”.
Position: [12.49337, 41.88989] latitude and longitude values give the position of Colosseo.
Categories: The place is classified in different categories:
- For example, “Historical Monument”, “Landmark-Attraction” and “Bicycle and Bicycle Accessories Shop”.
MatchScores: Indicates the accuracy of the address provided. The “Overall” value indicates the reliability score of the match, where 1 indicates complete accuracy.

With this answer, it is easy to access information about Colosseo, ranging from location information such as latitude, longitude and postal address provided by Amazon Location Service.

Step 3: Using the “SearchNearby API” to Find Places of Interest in the Neighborhood

We have the latitude and longitude of the Colosseum: [12.49337, 41.88989]. Now we will use Amazon Location Service's SearchNearby API to further explore the area surrounding this location. With this API, we can list popular and important places around the coordinates we set. For example, we can find restaurants, monuments or parking lots that are of interest to tourists. This feature is very effective for enriching the user experience in location-based applications.

The steps of using SearchNearby API can be as follows:

We have latitude and longitude data for the Colosseum: [12.4922, 41.8902].
Through a REST API client, we query points of interest located within a certain radius around these coordinates using the SearchNearby API.
We can customize the search using the Filter parameter. Thus, we can focus on a specific category, such as only restaurants or only historical monuments.

  ~ curl --slient -X "POST" "https://places.geo.${REGION}.amazonaws.com/v2/search-nearby?key=<API_KEY>" \
  > -d '{ "QueryPosition": [12.49337, 41.88989], "MaxResults": 5 }'

  "ResultItems": [
    {
      "PlaceId": "A...S",
      "PlaceType": "PointOfInterest",
      "Title": "Galleria della Metropolitana - Stazione Colosse",
      "Address": {
        "Label": "Galleria della Metropolitana - Stazione Colosse, Piazza del Colosseo, 00184 Roma RM, Italia",
        "Country": {
          "Code2": "IT", 
          "Code3": "ITA", 
          "Name": "Italia"
        },
        "Region": {
          "Name": "Lazio"
        },
        "SubRegion": {
          "Code": "RM", 
          "Name": "Roma"
        },
        "Locality": "Roma",
        "District": "Celio",
        "PostalCode": "00184",
        "Street": "Piazza del Colosseo",
        "StreetComponents": [
          {
            "BaseName": "Colosseo", 
            "Type": "Piazza del",
            "TypePlacement": "BeforeBaseName",
            "TypeSeparator": " ",
            "Language": "it"
          }
        ]
        "Position": [12.49368, 41.88992],
        "Distance": 26,
        "Categories": [
          {
            "Id": "food-beverage_specialty_store",
            "Name": "Food-Beverage Specialty Store",
            "LocalizedName": "Cibi e bevande specializzati",
            "Primary": True
          },
          ...
        ],
      }
    }
  ]

We used the SearchNearby API to find places of interest around Colosseum and set maxResults to 5 to list only the five closest results.

The SearchNearby API offers a Filter parameter that allows you to further customize the venue search results. With this parameter, you can get more specific results by specifying a number of attributes such as location, category or other business types. Now, let's learn more about how you can use the Filter parameter.

What are Filter Parameters?

BoundingBox: If you only want to search for places within a certain geographical area, you can use the BoundingBox parameter.
"BoundingBox": [12.492, 41.890, 12.500, 41.900]
ExcludeBusinessChains: Sometimes you may want to avoid large business chains. This is where ExcludeBusinessChains comes in.
"ExcludeBusinessChains": ["********"]
ExcludeCategories: If you want to see places outside a category, you can use the ExcludeCategories filter. For example, if you want to search for places other than restaurants and fast food places:
"ExcludeCategories": ["restaurant", "fast_food"]
ExcludeFoodTypes: Sometimes, you may want to exclude a certain cuisine. Let's say you don't want to search for restaurants that serve pizza or sushi:
"ExcludeFoodTypes": ["pizza", "sushi"]
IncludeBusinessChains: If you only want to see places belonging to a specific business chain, you can use the IncludeBusinessChains filter.
"IncludeBusinessChains": ["************"]
IncludeCategories: If you want to see places belonging to certain categories, you can use this filter to show only the categories you want. For example, if you only want to see museums and historical monuments:
“IncludeCategories": ["museum", "historical_monument"]
IncludeCountries: In some cases you may only want to see places in certain countries. For example, to see only places in Italy and France:
"IncludeCountries": ["IT", "FR"]
IncludeFoodTypes: If you want to target a food type, you can use the IncludeFoodTypes filter to include only places with that cuisine type. For example, to search for restaurants serving Italian and Mexican cuisine:
"IncludeFoodTypes": ["italian", "mexican"]

Let's say you are looking for places to eat around Colosseum and you only want to see places with Italian cuisine. In this case, you can filter as follows:

  {
    "Position": [12.49337, 41.88989],
    "MaxResults": 5,
    "Filter": {
      "IncludeFoodTypes": ["italian"]
    }
  }

Step 4: Creating a Driving Route between Cities

Planning a cross-city trip is now easy! I created a driving route from Rome to Milan using AWS CLI.

For this route calculation, I used the calculate-routes command. When the command ran, the results included a polyline for plotting the route on a map, and a detailed list of directions for each step of the drive, complete with the exact location of each turn, distances, and times - everything from simple steps such as “turn right” to full route information showing the time and distance at each step.

Having access to such practical and detailed route information with the AWS CLI is a great convenience for those who want to plan long-distance trips!

  curl --request POST \
    --url 'https://routes.geo.eu-central-1.amazonaws.com/v2/routes?key=Your_key' \
    --header 'Content-Type: application/json' \
    --data
    '{
      "Origin": [
        12.4964,
        41.9028
      ],
      "Destination": [
        9.1900,
        45.4642
      ],
      "TravelMode": "Car",
      "DistanceUnit": "Kilometers"
    }'

The output of this command is the polygon line of the route from Rome to Milan. Thanks to this polygon line, you can visualize the route on the map and understand the itinerary much more clearly. You can also follow each stage of the journey step by step with a detailed list of directions. This list includes important information such as the location of each turn, distances and times.

  "TravelMode": "Car",
  "Type": "Vehicle",
  "VehicleLegDetails": 
    {
      "TravelSteps": 
      [
        {
          "Duration": 15,
          "Distance": 75,
          "ExitNumber": [],
          "GeometryOffset": 0,
          "Type": "Depart"
        },
        {
          "Duration": 10,
          "Distance": 8,
          "ExitNumber": [],
          "GeometryOffset": 2,
          "Type": "Turn",
          "TurnStepDetails": {
            "Intersection": [],
            "SteeringDirection": "Right",
            "TurnIntensity": "Typical"
          }
        }
      ]
    },

As a result, with AWS Location Service, it is possible to plan long-distance trips and easily calculate routes. This powerful API offers a variety of advantages, from route calculations to detailed map visualizations. Now, with a few simple commands, you can plan every step of your journey more easily and quickly. It's really exciting to explore what AWS has to offer! Don’t forget to explore these tools on your next journey! 🚗💨