Point of Interest Catalog Schema

The Point of Interest (POI) catalog schema defines the standardized format for submitting POI data to Alexa+. Use it to surface accurate, current business and location information to customers through voice and other interfaces.

Overview

A POI is any named geographic location that is relevant to customers, including restaurants, hotels, gas stations, hospitals, electric vehicle (EV) charging stations, retail stores, and more. Alexa+ uses POI data to answer customer queries such as:

• "Alexa, find Italian restaurants near me."
• "Alexa, what are the hours for [your business name]?"
• "Alexa, is there EV charging nearby?"
• "Alexa, book a table at [xyz restaurant]."

Complete, accurate data submissions produce better Alexa+ responses and customer experiences.

Submission format

You must submit all POI records as JSON objects conforming to this schema. Each JSON object represents a single POI location.

Requirement levels

In this document, each field has one of three requirement levels:

Submission rules

• Each POI record must have a unique id that is stable across submissions.
• All URLs must use https:// or http:// and mustn't contain spaces.
• Locale codes must follow BCP-47 format (for example, en-US, ja-JP).
• Country codes must follow ISO 3166-1 alpha-2 format (for example, US, GB, FR).
• Currency codes must follow ISO 4217 3-letter format (for example, USD, EUR, JPY).

Field requirements at a glance

Top-level fields

id

Requirement: Required
Type: string

A unique, stable identifier for this POI. Alexa+ uses this ID to match records across submissions for updates and deduplication.

Example  

"id": "poi-12345-example-seattle-main"

name

Requirement: Required
Type: array of Name
Minimum items: one

The business name for this POI in one or more locales. Provide multiple entries to represent the same name in different locales, not to list alternate names. At least one entry is required. For alternate names, use the alternateNames field.

Example  

"name": [
  { "locale": "en-US", "name": "Starbucks" },
  { "locale": "ja-JP", "name": "スターバックス", "nameInKana": "スターバックス" }
]

address

Requirement: Required
Type: array of Address
Minimum items: one

The physical address(es) of the POI. At least one address is required. See the Address for required sub-fields and country-specific rules. Alexa+ treats the first entry in the array as the primary address.

location

Requirement: Recommended
Type: Location object

Geographic coordinates for the POI. If you omit this field, Alexa+ attempts to geocode the address, but Amazon strongly recommends that you supply precise coordinates.

operatingInfo

Requirement: Recommended
Type: OperatingInfo object

Operating hours, special hours, and closure status. Providing this data enables Alexa+ to answer questions like "Is [xyz business] open right now?"

phone

Requirement: Recommended
Type: string

The primary phone number for the business. Include the country code (for example, +1-xxx-xxx-xxxx).

Example  

"phone": "+1-206-555-0100"

website

Requirement: Recommended
Type: string (URL)

The official website URL for the business. Must begin with http:// or https://.

Example  

"website": "https://www.example.com"

categories

Requirement: Recommended
Type: array of string

A list of business category labels that best describe this POI. Use widely recognized category names and synonyms where possible (for example, "Coffee Shop", "Restaurant", "Gas Station", "Mexican restaurant", "Massage", "Convenience store", "Grocery Store").

Example  

"categories": ["Coffee Shop", "Café"]

alternateNames

Requirement: Optional
Type: array of string

Additional names the business may be known by, such as trade names, abbreviations, or commonly used nicknames.

Example  

"alternateNames": ["Starbucks Coffee", "SBUX"]

description

Requirement: Optional
Type: array of Description

Locale-specific descriptions of the business.

media

Requirement: Optional
Type: Media object

Photos and images of the business.

ratings

Requirement: Recommended
Type: Ratings object

User ratings, review counts, individual reviews, awards, and ranking information.

relationships

Requirement: Optional
Type: Relationships object

Identifies chain affiliations, business groups, and spatial containment relationships between POIs.

attributes

Requirement: Optional
Type: Attribute object

Detailed POI characteristics including amenities, cuisine types, parking, payment methods, and more.

priceRange

Requirement: Optional
Type: integer

A price level indicator from one to four.

Example  

"priceRange": 2

costForTwo

Requirement: Optional
Type: MonetaryValue object

The estimated average cost for two people at this establishment.

Example  

"costForTwo": { "currencyCode": "USD", "value": "45.00" }

alexaSupportedActions

Requirement: Recommended
Type: array of string enum

Specifies which task-completion actions Alexa+ can perform for this POI. Currently supports two values: BOOKING, DELIVERY. If you omit this field, Alexa+ can't perform task-completion actions for this POI.

Example  

"alexaSupportedActions": ["BOOKING", "DELIVERY"]

actionUrls

Requirement: Optional
Type: ActionUrls object

Deep-link URLs that users can use to initiate task-completion actions for this POI, such as booking or food ordering.

Example  

"actionUrls": {
  "bookingUrl": "https://www.exampleA.com/restaurant/12345",
  "orderFoodUrl": "https://www.exampleB.com/store/67890",
  "providerUrl": "https://www.exampleC.com/biz/bella-italia-seattle"
}

lastUpdated

Requirement: Optional
Type: string (ISO 8601 date-time)

The timestamp of the last update to this POI record. Format: yyyy-MM-ddTHH:mm:ssZ.

Example  

"lastUpdated": "2026-03-15T08:30:00Z"

Object definitions

Name · Address · Location · OperatingInfo · OperatingHours · SpecialHours · Media · Photo · Ratings · Review · User · Award · Ranking · Relationships · Attribute · ServiceLists · EVChargingPort · EVConnector · MonetaryValue · ActionUrls · Description

Name object

Represents a business name in a specific locale.

Example  

{
  "locale": "ja-JP",
  "name": "スターバックス",
  "nameInKana": "スターバックス"
}

Address object

Represents a physical address for a POI.

Conditional rule for stateOrRegion

stateOrRegion is required for all countries except France (FR), Spain (ES), and Great Britain (GB). For those three countries, stateOrRegion is optional.

Example (US)  

{
  "addressLine1": "2401 Utah Ave S",
  "city": "Seattle",
  "stateOrRegion": "WA",
  "postalCode": "98134",
  "countryCode": "US"
}

Example (France): stateOrRegion not required  

{
  "addressLine1": "12 Rue de Rivoli",
  "city": "Paris",
  "postalCode": "75001",
  "countryCode": "FR"
}

Location object

Geographic coordinate data for the POI.

Example  

{
  "displayPosition": "geo:47.5951,-122.3326",
  "navigationPosition": "geo:47.5942,-122.3318"
}

OperatingInfo object

Describes the hours of operation and closure status for a POI.

Example  

{
  "hours": [
    { "day": "MONDAY", "open": "09:00:00", "close": "21:00:00", "isOpen": true },
    { "day": "TUESDAY", "open": "09:00:00", "close": "21:00:00", "isOpen": true },
    { "day": "WEDNESDAY", "open": "09:00:00", "close": "21:00:00", "isOpen": true },
    { "day": "THURSDAY", "open": "09:00:00", "close": "21:00:00", "isOpen": true },
    { "day": "FRIDAY", "open": "09:00:00", "close": "22:00:00", "isOpen": true },
    { "day": "SATURDAY", "open": "10:00:00", "close": "22:00:00", "isOpen": true },
    { "day": "SUNDAY", "open": "10:00:00", "close": "20:00:00", "isOpen": true }
  ],
  "specialHours": [
    { "date": "2026-12-25", "isOpen": false }
  ],
  "isClosed": false
}

OperatingHours object

Represents operating hours for a single day of the week.

Example  

{ "day": "FRIDAY", "open": "07:00:00", "close": "23:00:00", "isOpen": true }

SpecialHours object

Represents operating hours for a specific date (for example, a public holiday or special event).

Example (holiday closure)  

{ "date": "2026-12-25", "isOpen": false }

Example (reduced hours)  

{ "date": "2026-11-26", "isOpen": true, "open": "10:00:00", "close": "17:00:00" }

Media object

Container for business photos and imagery.

Example  

{
  "primaryPhotoUrl": "https://example.com/photos/store-front.jpg",
  "photos": [
    {
      "url": "https://example.com/photos/interior.jpg",
      "caption": "Main dining area",
      "id": "photo-001"
    }
  ]
}

Photo object

Represents a single photo or image.

Example  

{
  "url": "https://example.com/photos/interior.jpg",
  "caption": "Main dining area",
  "id": "photo-001"
}

Ratings object

Aggregated ratings, reviews, awards, and ranking information for the POI.

Example  

{
  "rating": 8.5,
  "reviewCount": 1243,
  "awards": {
    "michelin": [
      {
        "awardType": "Michelin Star",
        "awardYear": "2025",
        "awardName": "One Michelin Star"
      }
    ]
  },
  "ranking": {
    "ranking": "#4 of 13",
    "rankingCategory": "Italian Restaurants",
    "rankingGeo": "Seattle, WA"
  }
}

Review object

Represents a single customer review.

Example  

{
  "text": "Great atmosphere, friendly staff. Food was delicious.",
  "id": "review-001",
  "rating": 8,
  "language": "en",
  "created": "2026-02-15T10:30:00Z",
  "url": "https://yelp.com/biz/example-restaurant/review123",
  "user": { "id": "user-001", "name": "Michael R." }
}

User object

Represents a reviewer.

Example  

{
  "id": "user-001",
  "name": "Sarah K.",
  "photoUrl": "https://example.com/users/sarah-k/photo.jpg"
}

Award object

Represents an award or recognition received by the POI.

Example  

{
  "awardType": "Michelin Star",
  "awardYear": "2025",
  "awardName": "One Michelin Star",
  "awardSmallImage": "https://example.com/awards/michelin-small.png",
  "awardLargeImage": "https://example.com/awards/michelin-large.png"
}

Ranking object

Represents curated ranking information for the POI.

Example  

{
  "ranking": "#3 of 142",
  "rankingPosition": "3",
  "rankingDenominator": "142",
  "rankingCategory": "Italian Restaurants",
  "rankingGeo": "Seattle, WA"
}

Relationships object

Defines how a POI relates to other POIs or business entities.

Example (store inside a mall)  

{
  "chainIds": ["chain-example-001"],
  "containedBy": "poi-98765-westfield-mall"
}

Attribute object

Detailed characteristics of the POI. All sub-fields are objects with string key-value pairs unless otherwise noted.

Example  

{
  "knownFor": "Award-winning espresso and seasonal drinks",
  "cuisine": { "primary": "Café", "secondary": "Bakery" },
  "amenities": { "wifi": "Free", "outdoorSeating": "true", "driveThru": "true" },
  "parking": { "type": "Street and Lot", "free": "true" },
  "payment": { "creditCard": "true", "mobilePay": "true", "cash": "true" }
}

ServiceLists object

For EV charging station POIs, use attributes.services.chargingPorts to provide detailed port-level data.

EVChargingPort object

Represents a single EV charging port.

EVConnector object

Represents a specific charging connector.

Example  

{
  "chargingPorts": [
    {
      "portId": "port-001",
      "network": "ChargePoint",
      "free": false,
      "costPerKwh": { "currencyCode": "USD", "value": "0.35" },
      "chargingLevels": ["LEVEL_2"],
      "connectorTypes": ["J_1772"],
      "connectors": [
        {
          "connectorId": "conn-001a",
          "connectorType": "J_1772",
          "chargingLevel": "LEVEL_2",
          "kilowatts": "7.2",
          "volts": "240",
          "amps": "30"
        }
      ]
    }
  ]
}

MonetaryValue object

Represents a monetary amount with currency.

Example  

{ "currencyCode": "USD", "value": "45.00" }

ActionUrls object

Deep-link URLs that users can use to initiate task-completion actions.

Example  

{
  "bookingUrl": "https://www.exampleA.com/restaurant/12345",
  "orderFoodUrl": "https://www.exampleB.com/store/67890",
  "providerUrl": "https://www.exampleC.com/biz/bella-italia-seattle"
}

Description object

A locale-specific text description of the business.

Example  

{
  "locale": "en-US",
  "description": "Award-winning Italian restaurant serving classic Roman dishes in a warm, family-run setting since 1987."
}

Format and validation rules

Date and time formats

Coordinate format

Geographic coordinates must use the geo: URI scheme:

geo:[latitude],[longitude]

• Latitude: -90.0 to 90.0
• Longitude: -180.0 to 180.0

Valid examples:

• geo:47.5951,-122.3326

• geo:-33.8688,151.2093

Invalid examples:

• 47.5951,-122.3326 (missing geo: prefix)

• geo:47.5951, -122.3326 (space not allowed)

URL format

All URL fields must:

• Begin with http:// or https://
• Contain no spaces

Locale codes

Regular expression pattern: ^[a-z]{2}-[A-Z]{2}$

Country codes

Regular expression pattern: ^[A-Z]{2}$ — two uppercase letters.

Currency codes

Regular expression pattern: ^[A-Z]{3}$ — three uppercase letters.

Monetary value

The value field in MonetaryValue objects must be a decimal string.

Sample JSON data

The following is a complete sample POI record demonstrating all key fields:

Sample JSON POI data  

{
  "id": "poi-98001-bella-italia-seattle",
  "name": [
    { "locale": "en-US", "name": "Bella Italia" }
  ],
  "alternateNames": ["Bella Italia Ristorante"],
  "address": [
    {
      "addressLine1": "1501 Pike Place",
      "addressLine2": "Suite 301",
      "city": "Seattle",
      "stateOrRegion": "WA",
      "postalCode": "98101",
      "countryCode": "US",
      "neighborhood": "Pike Place Market"
    }
  ],
  "location": {
    "displayPosition": "geo:47.6096,-122.3422",
    "navigationPosition": "geo:47.6095,-122.3421"
  },
  "phone": "+1-206-555-0188",
  "website": "https://www.bellaitaliaseattle.com",
  "categories": ["Italian Restaurant", "Fine Dining", "Restaurant"],
  "description": [
    {
      "locale": "en-US",
      "description": "Award-winning Italian restaurant serving classic Roman dishes in a warm, family-run setting since 1987."
    }
  ],
  "priceRange": 3,
  "costForTwo": { "currencyCode": "USD", "value": "85.00" },
  "operatingInfo": {
    "hours": [
      { "day": "MONDAY", "open": "11:30:00", "close": "22:00:00", "isOpen": true },
      { "day": "TUESDAY", "open": "11:30:00", "close": "22:00:00", "isOpen": true },
      { "day": "WEDNESDAY", "open": "11:30:00", "close": "22:00:00", "isOpen": true },
      { "day": "THURSDAY", "open": "11:30:00", "close": "22:00:00", "isOpen": true },
      { "day": "FRIDAY", "open": "11:30:00", "close": "23:00:00", "isOpen": true },
      { "day": "SATURDAY", "open": "12:00:00", "close": "23:00:00", "isOpen": true },
      { "day": "SUNDAY", "isOpen": false }
    ],
    "specialHours": [
      { "date": "2026-12-25", "isOpen": false },
      { "date": "2026-11-26", "isOpen": true, "open": "12:00:00", "close": "20:00:00" }
    ],
    "isClosed": false
  },
  "media": {
    "primaryPhotoUrl": "https://cdn.example.com/bellaitalia/exterior.jpg",
    "photos": [
      {
        "url": "https://cdn.example.com/bella-italia/dining-room.jpg",
        "caption": "Main dining room",
        "id": "photo-001"
      },
      {
        "url": "https://cdn.example.com/bella-italia/pasta.jpg",
        "caption": "House-made tagliatelle",
        "id": "photo-002"
      }
    ]
  },
  "ratings": {
    "rating": 9.1,
    "reviewCount": 2847,
    "awards": {
      "michelin": [
        {
          "awardType": "Michelin Star",
          "awardYear": "2025",
          "awardName": "One Michelin Star"
        }
      ]
    },
    "ranking": {
      "ranking": "#3 of 142",
      "rankingCategory": "Italian Restaurants",
      "rankingGeo": "Seattle, WA",
      "rankingPosition": "3",
      "rankingDenominator": "142"
    }
  },
  "relationships": {
    "containedBy": "poi-00001-pike-place-market"
  },
  "attributes": {
    "knownFor": "House-made pasta and award-winning tiramisu",
    "popularDishes": ["Tagliatelle Bolognese", "Risotto ai Funghi", "Tiramisu"],
    "cuisine": { "primary": "Italian", "regional": "Roman" },
    "menu": { "vegetarian": "true", "vegan": "available", "glutenFree": "upon request" },
    "alcohol": { "served": "Full Bar", "wine": "Extensive Italian wine list" },
    "attire": { "required": "Smart Casual" },
    "goodFor": { "dateNight": "true", "groups": "true", "businessDining": "true" },
    "amenities": { "reservations": "Recommended", "outdoorSeating": "false", "privateRoom": "true" },
    "parking": { "type": "Street and Garage", "free": "false", "validated": "true" },
    "payment": { "creditCard": "true", "cash": "true", "mobilePay": "true" }
  },
  "alexaSupportedActions": ["BOOKING"],
  "lastUpdated": "2026-03-01T00:00:00Z"
}

FAQs

The following FAQs cover common questions about the POI data schema.

Q: When is stateOrRegion required?

stateOrRegion is required for all countries except France (FR), Spain (ES), and Great Britain (GB). For all other countries, such as the United States, Canada, Germany, Japan, and Australia, you must include a value for stateOrRegion.

Q: My business doesn't have fixed hours. What should I submit?

If hours vary significantly or are unavailable, omit the operatingInfo.hours array entirely. Don't submit placeholder or estimated hours. If the business has no set hours but is always open, set each day's entry with "isOpen": true, "open": "00:00:00", and "close": "23:59:59".

Q: What happens if I don't provide location coordinates?

Alexa+ attempts to geocode the address to derive coordinates. However, geocoded coordinates may be less precise than Global Positioning System (GPS)-accurate coordinates. This is particularly true for businesses in dense urban areas, large campuses, or malls. Amazon strongly recommends that you provide location.navigationPosition for all records. If you omit displayPosition, Alexa+ automatically uses navigationPosition as the display position.

Q: Can a POI have multiple addresses?

Yes. The address field is an array that accepts multiple entries to support locale-specific translations of the same physical address. For example, a Japanese POI can include the same address in both English and Japanese locales. Don't use this array to submit different physical addresses.

Q: Should I include alexaSupportedActions?

Yes. For enabling booking or appointments, set this to ["BOOKING"]. For enabling food ordering, set this to ["DELIVERY"]. If you support both, set it to ["BOOKING", "DELIVERY"].

Q: How should I handle permanently closed POIs?

Set operatingInfo.isClosed to true. Don't delete the record from your feed immediately. Alexa+ needs the record to process the closure and suppress the POI from results. You may remove the record from future feeds after confirming the closure has been processed.

Q: How should I handle temporarily closed POIs?

Use operatingInfo.temporarilyClosedUntil with the last date that the POI is closed in yyyy-MM-dd format. Don't set isClosed to true for temporary closures, as that signals a permanent closure.

Q: The rating field goes to 10 but most services use a 5-star scale. Should I convert?

Yes, normalize your ratings to the 0–10 scale before submission. For example, submit a 4.25 out of 5 rating as 8.5.

Q: Are there any fields I shouldn't include if I don't have data?

Yes, omit fields for which you have no data rather than submitting empty strings or null values. The schema uses additionalProperties: false, which means any unexpected fields or improperly typed values cause validation failures.

Q: What's the id field used for?

The id is the stable, unique key for this POI across all submissions. Alexa+ uses it to match incoming updates to existing POI records, deduplicate submissions, and manage deletions. If you need to merge two records, contact your Alexa+ Solutions Architect team.

Related topics

• Create a Category Add-on Manually with the CLI

Last updated: Jul 10, 2026