Amazon Location Service Connector

The Amazon Location Service Connector provides geolocation services powered by Amazon Location Service, including place search and static map generation.

Operations

`searchPlaceByText`

Searches for places matching a text query, with optional bias toward a geographic location.

Parameters

Parameter	Type	Required	Default	Description
`query`	string	Yes	-	The search text (e.g., "coffee shop", "123 Main Street")
`latitude`	number	Yes	-	Latitude for location bias
`longitude`	number	Yes	-	Longitude for location bias
`maxResults`	number	No	`5`	Maximum number of results to return
`generateMapImages`	boolean	No	`false`	Whether to generate static map images for each result

Response Structure

Each result item includes:

Field	Type	Description
`Title`	string	Name of the place
`Position`	array	`[longitude, latitude]` coordinates
`Address.Label`	string	Full formatted address
`Address.AddressNumber`	string	Street number
`Address.Street`	string	Street name
`Address.Locality`	string	City or municipality
`Address.District`	string	Neighborhood or district
`Address.Region`	object	State or region information
`Address.Country`	object	Country information
`Address.PostalCode`	string	Postal/ZIP code
`Place`	object	Normalized place data (see below)
`mapImageUrl`	string	Static map image URL (if `generateMapImages` is true)

Examples

// Basic place search
{
    "query": "Starbucks",
    "latitude": 37.7749,
    "longitude": -122.4194,
    "maxResults": 3
}

// Output
{
  "result": [
    {
      "Title": "Starbucks",
      "Position": [-122.4089, 37.7855],
      "Address": {
        "Label": "789 Mission St, San Francisco, CA 94103, USA",
        "AddressNumber": "789",
        "Street": "Mission St",
        "Locality": "San Francisco",
        "Region": { "Name": "California" },
        "Country": { "Name": "United States" },
        "PostalCode": "94103"
      }
    }
  ]
}

// Search with map image generation
{
    "query": "Golden Gate Bridge",
    "latitude": 37.7749,
    "longitude": -122.4194,
    "maxResults": 1,
    "generateMapImages": true
}

// Output
{
  "result": [
    {
      "Title": "Golden Gate Bridge",
      "Position": [-122.4783, 37.8199],
      "Address": {
        "Label": "Golden Gate Bridge, San Francisco, CA, USA"
      },
      "mapImageUrl": "https://cdn.example.com/static-maps/abc123-def456.jpg"
    }
  ]
}

// Address search
{
    "query": "1600 Pennsylvania Avenue NW, Washington DC",
    "latitude": 38.8977,
    "longitude": -77.0365,
    "maxResults": 1
}

// Output
{
  "result": [
    {
      "Title": "1600 Pennsylvania Avenue NW",
      "Position": [-77.0365, 38.8977],
      "Address": {
        "Label": "1600 Pennsylvania Avenue NW, Washington, DC 20500, USA",
        "AddressNumber": "1600",
        "Street": "Pennsylvania Avenue NW",
        "Locality": "Washington",
        "Region": { "Name": "District of Columbia" },
        "Country": { "Name": "United States" },
        "PostalCode": "20500"
      }
    }
  ]
}

Using with Context Variables

{
    "query": "{{context.parameters.searchQuery}}",
    "latitude": "{{context.parameters.userLatitude}}",
    "longitude": "{{context.parameters.userLongitude}}",
    "maxResults": 5,
    "generateMapImages": true
}

Static Map Generation

When generateMapImages is set to true, the connector:

Generates a 400x400 pixel static map image for each result
Centers the map on the place's coordinates at zoom level 16
Adds a red marker with the place's title as a label
Uploads the image to S3 with a 7-day expiration
Returns the CDN URL in the mapImageUrl field

Map Image Specifications:

Property	Value
Dimensions	400 x 400 pixels
Format	JPEG
Map Style	Standard
Zoom Level	16
Marker Color	Red (#EE4B2B)
Marker Size	Large
Text Color	White (#FFFFFF)
Expiration	7 days

Error Handling

Error Condition	Behavior
Invalid coordinates	AWS SDK throws validation error
No results found	Returns empty array `[]`
Map generation fails	Result returned without `mapImageUrl` field
Unsupported operation	Throws `Operation '{name}' not supported`

Usage Examples

Finding Nearby Restaurants

{
    "query": "Italian restaurant",
    "latitude": 40.7128,
    "longitude": -74.0060,
    "maxResults": 5
}

Generating Location Cards with Maps

{
    "query": "{{context.userMessage}}",
    "latitude": "{{context.session.location.latitude}}",
    "longitude": "{{context.session.location.longitude}}",
    "maxResults": 3,
    "generateMapImages": true
}

The results can then be used to generate rich location cards with embedded map images.