Nov 26, 2018
Here Geocode App & AWS SAR
by Jessica Ellis and Lynn Langit
Learning API Programming
In the second episode of this series, we’ll walk you through a Codelab tutorial which uses the HERE Technologies Geocode Serverless Application. This application template is hosted in the AWS Serverless Application Repository (AWS SAR) and it designed to be integrated into your application, so that you can easily invoke the HERE Geocoder API. In this post (and accompanying screencast) we’ll cover the key steps so that you can quickly build this code sample using the Codelab tutorial (shown below) —> link. All of the documentation, blog posts and sign-up instructions can be found on the HERE | AWS Serverless Application Page.
You may recall from Part One of this series, that our first post guided you through the process of using a single script to call HERE APIs. That script was hosted in a Lambda and invoked geocoding with a call to HERE Technologies Geocoder API —> link.
In this blog post you will be working with a simplified microservices application pattern. The diagram below illustrates the services included in this pattern. We’ll show how you can use the HERE Technologies Geocode Application which is designed to integrate into the AWS Services as shown below. In order to create and test your sample application, you’ll need to configure a Cloud Formation template (which is part of the AWS Serverless Application Repository) and will use the HERE Geocode Application.
Why use the Geocoder API with AWS?
The HERE Geocoder API allows a user to enter an address, the name of a landmark, or place of interest and the API returns the geo-coordinates (lat/long) of that location. The HERE Geocoder is used in many large-scale, enterprise and commercial applications, such as navigation systems installed in cars and also by online commerce to create efficient and accurate delivery routes. In this sample you’ll work with two additional capabilities of the the Geocoder API. First, it can return complete address information if incomplete address information is sent to it. Second, it can provide a list of possible locations using one or more keywords.
Using HERE APIs allows you to integrate location services into your applications with greater speed and ease. Working with this code sample, which uses an AWS API Gateway and two AWS Lambdas, you can build a working sample quickly and easily. This application design implements a microservices pattern which calls the HERE location services and partitions the remote methods calls into one Lambda per method call.
How to use the HERE Geocoder REST API with AWS
In the first section of the Codelab tutorial (step 1), you set up your service access by creating an account on the HERE Developer Portal. In order to build this example application yourself, you will need to sign up for the required services. In most cases, you will be able to use the FREE tier of both services (HERE and AWS) while you are testing.
1. Set up an account on the HERE Developer Portal, Free Account.
2. Set up an account with Amazon Web Services (AWS),
Verify a Call to the HERE Geocoder API
In sections 2 and 3 of the Codelab tutorial, you use a free web client tool to setup and test a call from your browser to the HERE Geocoder API. You’ll use JSFiddle to verify that your HERE developer credentials are working properly. To do so, open https://jsfiddle.net and follow steps 2 and 3 of the tutorial. These steps allow you to call the HERE Geocode REST API directly.
This verification step requires you to obtain credentials directly from HERE: “App ID” and “App Code”. After signing up for the free account, navigate to the “Products” tab and click “REST APIs”, click “Get Free API Key” and enter the “App ID” and “App Code” to lines 4 and 5 of the JavaScript sample code.
After you have updated lines 4 and 5 of the sample code with your credentials, then click the ‘RUN’ button on the JSFiddle tool to run your code. Next click the ‘Geocode!’ button on the rendered web page to verify that your HERE credentials work as expected.
Your screen should look similar to the sample below after you have successfully called the HERE Geocoder REST API directly from your jsfiddle client. You’ll see output (example shown below) that the HERE API successfully completed a partial address.
Understand the AWS Serverless Application Repository
The AWS SAR (Serverless Application Repository) is one of the options you can use to create an AWS Lambda function. It’s available in the AWS console, after you click the ‘Create function’ button, as shown in the screenshot below. The AWS SAR contains templates, which are called applications, because they create one more service AWS service instances (Lambda(s) plus other services). Search for ‘geocode’ to locate the HERE Technologies Geocode application template.
When you use the AWS SAR to create a Lambda, you are actually executing a CloudFormation template to create one or more Lambda instances and also other AWS service objects (in our case an API Gateway instance). The set of service instances you create with a CF template is called a CF stack. The general flow is shown below.
Using the AWS SAR HERE Geocode Application allows you to quickly set up your own microservices sample application. You use a Cloud Formation template which creates AWS service instances which is called a CF stack. In our case, the particular Cloud Formation template (or .yaml file) includes instructions which AWS will use to create service instances for all of the objects shown in the architecture diagram at the beginning of this article.
Working with service configuration as code is a best practice for AWS.
Using CloudFormation, you can set up, update, or remove service instances and their associated configuration quickly and consistently. This method of creating service instances is preferred to ‘clicking on services’ in the AWS console when setting up services for any type of production-level application. The reason is that you should be building services with a set of reproducible service settings. You can and should check your CF templates into source control in production scenarios as well.
Use the AWS Serverless Application Repository
Follow tutorial Step 4 to deploy the HERE Geocode Serverless Application from the AWS SAR. As part of this action, you will need to configure the HERE Geocode application CF template parameters.
In the CF template interface, be sure to enter your HERE developer credentials into the template parameter text boxes (note the position of the “App ID” & “App Code” text boxes in the screenshot to the left).
This CF template creates an instance of the API Gateway and two Lambdas. One lambda calls the ‘auto-complete address’ method, the other Lambda calls the ‘point of interest’ method.
After these service instances are created, you will be able to use your API Gateway endpoint from JSFiddle to verify that you can send information from your web client to AWS and on to HERE Technologies. You will also verify that you receive the expected information back through your application from the dashboard on the HERE Developer Portal.
Verify and Test the Setup
After the CF stack object are created, you can view each Lambda in the AWS Lambda console. An example is shown below.
After you verify that the AWS service instances have been created, then you’ll want to test your microservice, by calling the HERE Geocoder API from your JSFiddle client via the API Gateway. These steps are detailed in the tutorial as well.
Here is short screencast which shows all of the steps in this tutorial.
https://www.youtube.com/watch?v=j_j0ppq4VJE
Tip: To delete all service instances (i.e. the lambdas and the API Gateway instance), go to AWS Cloud Formation, find the stack name, select it, then click on ‘Actions -> Delete Stack’
What Did We Learn
In the post, we covered the key steps for you to quickly set up an AWS microservice which calls the HERE Technologies Geocoder API using API Gateway and lambdas. You also worked with the AWS Serverless Application Repository and implemented its associated Cloud Formation template to implement an application stack.
Patterns in this application show by example some of the key aspects of integrating HERE Technologies API services into your production AWS applications in production.
