Prerequisites

Before you begin geocoding, reverse geocoding or searching for places, follow the prerequisite steps:

Create a place index resource

Begin by creating a place index resource in your AWS account.

When you create a place index resource, you can choose from the data providers available to support queries for geocoding, reverse geocoding, and searches:

1. Esri – For more information about Esri's coverage in your region of interest, see Esri geocoding coverage in this guide.

2. HERE Technologies – For more information about HERE's coverage in your region of interest, see HERE geocoding coverage in this guide.

You can do this using the Amazon Location Service console, the AWS CLI, or the Amazon Location APIs.

Console

To create a place index resource using the Amazon Location Service console

1. Open the Amazon Location Service console at https://console.aws.amazon.com/location/.

2. In the left navigation pane, choose Place indexes.

3. Choose Create place index.

4. Fill out the following boxes:

   • Name – Enter a name for the place index resource. For example, ExamplePlaceIndex. Maximum 100 characters. Valid entries include alphanumeric characters, hyphens, periods, and underscores.

   • Description – Enter an optional description.

5. Under Data providers, choose an available data provider to use with your place index resource.

   Note

   If your application is tracking or routing assets that you use in your business, such as delivery vehicles or employees, you may only use HERE as your geolocation provider. For more information, see section 82 of the AWS service terms.

6. Under Data storage options, specify if you intend to store search results from your place index resource.

7. (Optional) Under Tags, enter a tag Key and Value. This adds a tag your new place index resource. For more information, see Tagging your resources.

8. Choose Create place index.

API

To create a place index resource using the Amazon Location APIs

Use the CreatePlaceIndex operation from the Amazon Location Places APIs.

The following example is an API request to create a place index resource called ExamplePlaceIndex using the data provider Esri.

POST /places/v0/indexes
Content-type: application/json

{
   "DataSource": "Esri",
   "DataSourceConfiguration": { 
      "IntendedUse": "SingleUse"
   },
   "Description": "string",
   "IndexName": "ExamplePlaceIndex",
   "Tags": { 
      "Tag1" : "Value1" 
   }
}

AWS CLI

To create a place index resource using AWS CLI commands

Use the create-place-index command.

The following example creates a place index resource called ExamplePlaceIndex using Esri as the data provider.

aws location \
  create-place-index \
  --data-source "Esri" \
  --description "Example place index" \
  --index-name "ExamplePlaceIndex" \
  --tags Tag1=Value1

Note

Billing depends on your usage. You may incur fees for the use of other AWS services. For more information, see Amazon Location Service pricing.

Authenticating your requests

Once you create a place index resource and you're ready to begin building location features into your application, choose how you would authenticate your requests:

• To explore ways you can access the services, see Accessing Amazon Location Service.

• If you have a website with anonymous users, or you want to use your own authentication process, or combine multiple authentication methods, see Allowing unauthenticated guest access to your application using Amazon Cognito.

  Example

  The following example shows the passing of the unauthenticated identity pool as credentials when using the AWS JavaScript SDK.

  const AWS = require("aws-sdk");
  
  const credentials = new AWS.CognitoIdentityCredentials({
     IdentityPoolId: "us-east-1:54f2ba88-9390-498d-aaa5-0d97fb7ca3bd" 
  });
  
  const client = new AWS.Location({
     credentials,
     region: AWS.config.region // region containing the identity pool
  });
  
  // rsp.Results contains search results for geocoding
  const rsp = await location.searchPlaceIndexForText({
      IndexName: "ExamplePlaceIndex",
      Text: "Anyplace",
      BiasPosition: [-123.4567, 45.6789]
  }).promise();