Introduction

Duration is 3 min

This tutorial will walk you through the steps to add the HERE Geocoder Autocomplete API to the sample web application Waterfall Express.

This tutorial demonstrates concepts of microservices by introducing the AWS Serverless Application Repository (AWS SAR) and the HERE Geocoder Serverless Application made available by HERE Technologies.

Scenario

You are creating the web site for a start-up specializing in bespoke Adventure Travel Itineraries: Waterfall Express.

Clients select their starting point and multiple destinations by searching for locations of interest. Waterfall Express then plans and displays the route based on the client’s preferred mode of transport.

This is the second step of several towards a feature rich online experience, with this tutorial focusing on the tasks of adding an “autocomplete” to the search dialog and deploying an AWS SAR proxy for the Geocoder Autocomplete API.

What is the Geocoder Autocomplete API

What is the Geocoder Autocomplete API?

"The HERE Geocoder Autocomplete API is a REST API that you can integrate into web applications to help users obtain better results for address searches with fewer keystrokes. Spatial and region filters can be used to return suggestions with greater relevance to end users, such as results that are within a specified country or in the proximity of the current location.

The Geocoder Autocomplete API retrieves a complete address and an ID. You can subsequently use the Geocoder API to geocode the address based on the ID and thus obtain the geographic coordinates of the address."

Why Use the Geocoder Autocomplete API?

What you’ll learn

• How to call the HERE Geocoder Autocomplete REST API
• How to How to deploy a Serverless Application from the AWS SAR, and the benefits of Serverless Applications.
• How to centralize the App ID and App Code using the AWS SAR, so those secrets are not distributed in client-side code.

What you’ll need

• Access to an account with HERE Location Services
• Access to an account with Amazon Web Services (AWS)

What is a Proxy

In this tutorial, the term “proxy” refers to an intermediary between the caller of an API and the implementation of the API.

A proxy is important when calling external APIs for many reasons, including:

• Unexpected failures need to be handled gracefully
• Credentials need to be managed centrally
• Version changes of the external API may need to be masked from various callers

For more information on these various patterns, please see Microservices Patterns, for example the Circuit Breaker, as described on martinfowler.com.

For those who are familiar with Enterprise Integration Patterns, a related topic is the Smart Proxy.

What is the Geocoder Serverless Application?

The Geocode Serverless Application consists of an API Gateway and two Lambdas.

The purpose of the Geocode Serverless Application is to be a proxy - an intermediary - between your application and the Geocoder REST API.

The Geocode Serverless Application consists of two Lambdas because there are two REST methods related to Geocoding: the traditional Geocoder, and the user experience supporting variation known as Geocoder Autocomplete API.

Why use a Serverless Application as a Proxy for Geocoder

One of the benefits of using the Geocode Serverless Application as a proxy is the ability to centrally manage your API credentials (App ID and App Code).

Another benefit is the cache feature of the API Gateway which can significantly improve performance for your application and perhaps reduce costs by reducing the number of calls passed through to the external Geocoder REST API.

In addition, you benefit from all the features of AWS API Gateways and AWS Lambdas because you can modify the deployed Serverless Application in-place. In this tutorial we will see how to modify a Lambda.

Get set up

Duration is 3 min

Set up a HERE Location Services Account

Set up an account with HERE Location Services.

Set up an AWS Account

Set up an account with Amazon Web Services (AWS).

Deploy the Sample

Complete the procedure in the tutorial “Waterfall Express: JavaScript” to deploy the sample web site and add the map.

Once you have the map displayed as above, you are ready to proceed with this lab.

Add Autocomplete

Duration is 12 min

In this step we will add jQuery code to run whenever a key is released while typing in the main search input field. With each “key up” event the jQuery will call the HERE Geocoder Autocomplete REST API directly to retrieve suggestions.

Edit the file index.html and add the below JavaScript to the file just below this line:

An AJAX call is made to the HERE Technologies Geocoder Autocomplete REST API on each “key up” event captured by jQuery.

$("#auto-complete").keyup(function () {

    var searchtext = $("#auto-complete").val();

    var params = '?query=' + encodeURIComponent(searchtext) +
       '&beginHighlight=' + encodeURIComponent('<mark>') +
       '&endHighlight=' + encodeURIComponent('</mark>') +
       '&maxresults=5' +
       '&apiKey=' + YOUR-API-KEY;

    $.ajax({
       url: AUTOCOMPLETION_URL + params,
       type: 'get',
       dataType: 'json',
       success: onAutoCompleteSuccess,
       error: onAutoCompleteFailed,
    });
});

Take note of the params variable. This variable contains the query string parameters for the URL to be called through AJAX and is constructed by adding all the parameters needed by the API.

Update the assignment code at the top of the file to use your unique APPLICATION_ID and APPLICATION_CODE.

Once you have added the above jQuery code, upload the updated index.html to S3 and test your web site by entering “dettifoss” into the search dialog. You should see the autocomplete options displayed as below:

Deploy from AWS SAR

Duration is 6 min

In this step we deploy the Geocoder Serverless Application from the AWS Serverless Application Repository (SAR).

Navigate to AWS SAR

Navigate to https://console.aws.amazon.com/lambda and click Create Function.

On the next screen select Serverless Application Repository.

Use the search to locate the Geocode Serverless Application shown below.

Click on Geocode.

Configure application parameters

This deployment of the Serverless Application from AWS SAR requires input parameters. These parameters are shown at the bottom right of the screen, as shown in the screenshot below.

The Geocode Serverless Application requires the App ID and App Code previously obtained by signing up at here.com.

Click Deploy and watch AWS CloudFormation do all the work for you!

Explore the Serverless Application

Duration is 6 min

Once the deployment completes successfully (all green Status similar to the below screenshot), click on “View CloudFormation Stack”.

An error message may be displayed if you click on the “View CloudFormation Stack” link too soon, or if you switch between multiple AWS Regions. You can always start navigating again from the AWS Console home page to ensure you select the correct CloudFormation Stack.

AWS CloudFormation

Look in the section named Outputs for the HTTP endpoint through which we will call the geocoder API.

Copy the Value from the Outputs section for the key HereApiURL - you’ll need it in the next step.

The above step confirms that the AWS SAR deployment completed successfully: an AWS CloudFormation Stack was created, and as part of that Stack a Lambda was deployed and configured with the provided values for the Environment Variables. The deployed API Gateway is serving the shown “Invoke URL” and will pass requests to the Lambda for processing.

Update the Serverless Application

Duration is 8 min

One of the advantages of using a Serverless Application is the ability to modify the deployed services. In this example we must modify the AWS Lambda to ensure the caller receives a specific HTTP Response Header to ensure compliance with CORS.

Spot the Error: if you attempt to call the Geocoder Serverless Application prior to adding CORS support, jsFiddle may fail silently. You can see the error details by pressing F12 to open your browser’s developer tools - in the Console it should show the error relating to a missing HTTP Response Header.

Navigate to the AWS CloudFormation Stack deployed above, expand the section labelled Resources, and find the Resource of type “Function”. Click the name in the column Physical ID to navigate to the AWS Lambda “Geocode Suggest Function”.

On the Lambda configuration page, in the section titled “Function Code”, navigate to geocodesuggest.js and remove the two forward slash characters (“//”) on line 57 as highlighted below.

By adding the below line of code, the Lambda will add an HTTP Response Header when responding to requests through the API Gateway. You may edit the code of the Lambda to fit your requirements, for example replacing the asterisk with the domain of your web site from which you’re calling the Lambda.

Remember to click Save after editing the Lambda.

Now that you have updated the Lambda, proceed to updating the calling jQuery to point to the Lambda.

Redirect API call

Duration is 5 min

Now that you have the Geocode Serverless Application deployed you can replace the complex URI with a simpler pattern thanks to the combination of an AWS API Gateway and an AWS Lambda.

Update the variable AUTOCOMPLETION_URL with the Invoke URL endpoint deployed above and append “geocodesuggest” to match the path required for the AWS API Gateway and Lambda as shown in the screenshot below.

And update the JavaScript to remove the App ID and App Code from the params assignment.

The source code will become:

$("#auto-complete").keyup(function () {

    var searchtext = $("#auto-complete").val();

    $.ajax({
        url: AUTOCOMPLETION_URL + encodeURIComponent(searchtext),
        type: 'get',
        dataType: 'json',
        success: onAutoCompleteSuccess,
        error: onAutoCompleteFailed,
    });
});

As shown in the below screenshot:

Remember to save the edited file and upload it to S3 again.

If the lambda was updated correctly in the steps above, you should be able to retrieve multiple results as in the example below.

Review

Duration is 2 min

When you see the below search suggestions you have successfully completed this lab!

You have successfully added jQuery to react to user input, provide search suggestions based on the Geocoder Autocomplete API, and then replaced the direct API call with a call via an AWS API Gateway & Lambda from the AWS SAR, which you deployed into your AWS account.

Glossary

AWS

What is AWS API Gateway

The AWS API Gateway is a layer between the caller and the implementation, providing services to the consumers of APIs and the publishers of APIs, including monitoring, authentication, and facilitating API-related management tasks such as versioning.

In this tutorial we will deploy an AWS API Gateway to benefit from its ability to modify incoming requests. We will modify the incoming request to add the App ID and App Code previously obtained from here.com.

In this tutorial you will see the benefits of using an AWS API Gateway by first creating a call to the Map Image REST API directly. Then you will substitute the direct call with a call through the AWS API Gateway.

What is a Lambda

The AWS Lambda is a snippet of code associated with an event. In this tutorial we will attach a snippet of JavaScript to an HTTP endpoint. The HTTP endpoint will be provided by an AWS API Gateway. On receiving an HTTP request, the API Gateway will invoke the JavaScript we provided.

To get the most out of this tutorial, please familiarize yourself with AWS Lambdas.

What is Serverless

The term serverless was first associated with AWS Lambda because there is no management or cost overhead imposed for the underlying servers.

In this tutorial you will use a Serverless Application published by Here Technologies. The Geocoder Serverless Application consists of one AWS API Gateway and two AWS Lambdas. The Serverless Application will be deployed to your AWS account, but you will only be charged for usage, and there are no servers (EC2 instances) for you to manage, hence serverless.

For an in depth discussion on the terminology and related microservices approach to architecture, start with this article on Serverless.

What is AWS SAR

In 2017 AWS launched an “app store” for Serverless Applications. Named the AWS Serverless Application Repository (AWS SAR), it is a collection of open source Serverless Applications published by various vendors and open source developers.

Serverless Applications published in the AWS SAR are described using the Serverless Application Model. You should review the SAM provided at the time of deployment, known as a Template, and the related source code because the AWS SAR deployment will be to your AWS account.