Hands on

Developing with Map Images Using AWS Serverless Applications

By Michael Palermo | 14 August 2018

Last year at the AWS re:Invent conference, HERE announced the availability of ten applications through the newly launched AWS Serverless Application Repository. At the time of the announcement, the repository was in beta and invite-only. Now any developer can deploy from many of the public applications availabe in the repository to quickly create a custom configurable microservice. For a bit more understanding of the benefits of the AWS Serverless Application Repository please visit our post introducing the HERE geocode service using the repository.

This post will guide you through the process of discovering, selecting, and deploying the HERE MapImage Serverless Application for use in your development projects. This will allow you to access custom map images from HERE via your own custom API. To accomplish this, you will need credentials at the following:

Discovering the HERE MapImage Serverless App

After account credentials are confirmed, to find the HERE MapImage application, browse to the AWS Serverless Application Repository.

AWS Serverless Application Browse

After clicking the "Browse all applications" button, you will be prompted to do your search. Type "HERE MapImage" as shown below, then select the MapImage title in the results shown.

MapImage Serverless Application Search

The landing page for the MapImage application is shown. You are now ready to deploy.

Deploying the HERE MapImage Serverless App

What does deploy mean in this context? It means installing in your AWS environment all the code and resources needed for you to manage your own serverless app. Once the HERE MapImage application is deployed, it is now your serverless app. Deployment is so easy! Just click the "Deploy" button to start the process.

Deploy MapImage Serverless Application

You will prompted to provide three values.

MapImage application parameters

You can name the application whatever you choose - just know it is used to help identify resources related to your custom serverless app. The "HereAppCode" and "HereAppId" fields are filled with values you receive from your HERE developer account. Once the fields are filled in, click the "Deploy" button. It will take a little time for the deployment process to complete. The process is finished once you see the "Application successfully deployed!" message as shown here.

MapImage application successfully deployed

In the resource list shown in the right panel, click on the "MapImageFunction" link. This will take you to the underlying lambda created. Once there, you are ready for the next step.

Configuring Your Map Image Service

As mentioned before, now that the MapImage application and related resources are now deployed in your environment, you are in total control of what do do from here. Techncially, you wouldn't need to do anything else to start using the service, as long as your client is not a web page. However, since this post will show how to call your custom map image service from a web page, it provides an opportunity to explore some of the resources deployed into your environment.

From the previous step, you should be on the landing page for the custom "MapImageFunction" lambda. Near the top of the page, you will notice a visualization of the associated triggers and resources.

lambda triggers and resources

The only trigger for the lambda is the API Gateway. In other words, it will be a call to your custom API that will trigger the code in the lambda. What does your custom API look like, and how can you call it from a client? To observe what was created for you, click on the "API Gateway" box in the visualization.

API Gateway details

You will see the API Gateway results appear on the page. If details are collapsed, expand them to view everything. For your benefit, copy the URL designated as the API endpoint and save for a future step. The API endpoint URL is used by client apps to call your custom map image service. Once you have copied the URL, click on the link residing above the details.

API Gateway resources actions

On the page for the API Gateway, make sure the section selected on the left side is "Resources", and the root node "/" is also selected. Next, click the "Actions" drop down menu. Click on the "Enable CORS" menu item. Accept the default prompts, and return to the "Actions" menu. Now click the "Deploy API" menu item. If prompted to what environment to deploy to, choose "Prod" for now, since the API endpoint URL copied earlier resides there. The redeployment takes very little time, and you are now ready to test.

Consume Your Map Image Service

Listed below is the HTML client in it's entirety:



Take note of line 11. You will need to replace the value with the data you have in your API Gateway endpoint URL copied earlier. Line 12 concatenates query string parameters to indicate coordinates [c], width of image [w], height of image [h], and zoom level [z]. Lines 14-22 make an asynchronous call to your custom API and return the results. Because the data returned is base64 encoded, it is designated as such with the data moniker shown on line 18. Executing the page results with an image! In this example, getting a view of the author's hometown.

Map image result, Phoenix

Summary

HERE is proud to be among the initial contributors to the AWS Serverless Repository - launching ten applications which map to core HERE APIs. In this post, you learned how to discover, deploy, configure, and test your own microservice derived from the HERE MapImage serverless application. In upcoming posts, we will explore how to use some of the other serverless applications provided by HERE.

For a recap of the benefits of deploying a application from the serverless repository, plese view the segment from the AWS RE:invent session below: