Point of Interest Catalog Schema - Alexa+ Developer Docs

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:

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:

Label	Meaning
Required	Must be present in every record. Alexa+ rejects any submission that is missing a required field.
Recommended	Strongly encouraged. Omitting recommended fields reduces data quality and may limit Alexa+ features.
Optional	You should provide it when available. It enhances the richness of the POI record.

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

Field	Type	Requirement
id	string	Required
name	array of Name	Required (minimum one)
address	array of Address	Required (minimum one)
location	Location object	Recommended
operatingInfo	OperatingInfo object	Recommended
phone	string	Recommended
website	string (URL)	Recommended
categories	array of string	Recommended
ratings	Ratings object	Recommended
alexaSupportedActions	array of string enum	Recommended
alternateNames	array of string	Optional
description	array of Description	Optional
media	Media object	Optional
relationships	Relationships object	Optional
attributes	Attribute object	Optional
priceRange	integer (1-4)	Optional
costForTwo	MonetaryValue object	Optional
actionUrls	ActionUrls object	Optional
lastUpdated	string (ISO 8601 date-time)	Optional

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

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"

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.

Value	Meaning
1	Inexpensive
2	Moderate
3	Expensive
4	Very expensive

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.

Value	Description
”BOOKING”	Alexa+ can initiate a reservation or appointment booking
”DELIVERY”	Alexa+ can initiate a food delivery order

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.

Field	Type	Requirement	Description
name	string	Required	The business name. Must be at least one character.
locale	string	Optional	Locale code in BCP-47 format (for example, `en-US`, `ja-JP`). Regular expression pattern: `^[a-z]{2}-[A-Z]{2}$`
nameInKana	string	Optional	Phonetic Kana pronunciation. Use for Japanese-language POIs.

Example

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

Address object

Represents a physical address for a POI.

Field	Type	Requirement	Description
addressLine1	string	Required	Primary street address (for example, “123 Main St”).
city	string	Required	City name.
postalCode	string	Required	Postal or ZIP code.
countryCode	string	Required	ISO 3166-1 alpha-2 two-letter country code (for example, `US`, `DE`). Regular expression pattern: `^[A-Z]{2}$`
stateOrRegion	string	Required*	State, province, or region. See the conditional rule for stateOrRegion.
addressLine2	string	Optional	Secondary address line (for example, suite, floor, unit).
addressLine3	string	Optional	Additional address line.
districtOrCounty	string	Optional	District or county name.
neighborhood	string	Optional	Neighborhood name.
crossStreets	string	Optional	Intersecting street names (for example, “Corner of 1st Ave & Pike St”).

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.

Field	Type	Requirement	Description
displayPosition	string	Optional	Coordinates for map display. Format: `geo:[lat],[lon]` (for example, `geo:47.5951,-122.3326`). If not provided, Alexa+ uses `navigationPosition` as the display position.
navigationPosition	string	Recommended	Coordinates for navigation/routing. Same format as `displayPosition`.
bbox	string	Optional	Bounding box coordinates representing the POI’s geographic footprint.

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.

Field	Type	Requirement	Description
hours	array of OperatingHours	Optional	Regular weekly operating hours.
specialHours	array of SpecialHours	Optional	Hours for holidays or special dates. These override regular hours for the specified dates.
pickupHours	array of OperatingHours	Optional	Hours specifically for curbside/in-store pickup.
deliveryHours	array of OperatingHours	Optional	Hours specifically for delivery service.
isClosed	boolean	Optional	Set to `true` if the POI is permanently closed.
temporarilyClosedUntil	string (date)	Optional	Date through which the POI is temporarily closed. Format: `yyyy-MM-dd`.

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.

Field	Type	Requirement	Description
day	string enum	Required	Day of the week. One of: `SUNDAY`, `MONDAY`, `TUESDAY`, `WEDNESDAY`, `THURSDAY`, `FRIDAY`, `SATURDAY`
isOpen	boolean	Optional	Whether the business is open on this day. Set to `false` for days the business is closed.
open	string	Optional	Opening time. Format: `HH:mm:ss` (24-hour clock, for example, `09:00:00`).
close	string	Optional	Closing time. Format: `HH:mm:ss` (24-hour clock, for example, `22:00:00`).

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).

Field	Type	Requirement	Description
date	string (date)	Required	The specific date. Format: `yyyy-MM-dd`.
isOpen	boolean	Required	Whether the business is open on this date.
open	string	Optional	Opening time. Format: `HH:mm:ss` (24-hour). Include this field if `isOpen` is `true`.
close	string	Optional	Closing time. Format: `HH:mm:ss` (24-hour). Include this field if `isOpen` is `true`.
open24	boolean	Optional	Set to `true` if the business is open 24 hours on this date.

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.

Field	Type	Requirement	Description
primaryPhotoUrl	string (URL)	Optional	URL of the primary or featured photo for the business.
photos	array of Photo	Optional	Additional photos of the business.

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.

Field	Type	Requirement	Description
url	string (URL)	Required	Direct URL to the photo. Must begin with `http://` or `https://`.
caption	string	Optional	Descriptive caption for the photo.
slideshowUrl	string (URL)	Optional	URL to a slideshow version of the image.
id	string	Optional	Unique identifier for the photo.

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.

Field	Type	Requirement	Description
rating	number	Optional	Aggregate user rating. Scale: 0.0 to 10.0.
reviewCount	integer	Optional	Total number of user reviews. Must be ≥ 0.
reviews	array of Review	Optional	Individual user reviews.
awards	object	Optional	Awards keyed by award program name. Each value is an array of Award objects.
ranking	Ranking object	Optional	Curated ranking information (for example, “#4 of 13 restaurants in Seattle”).

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.

Field	Type	Requirement	Description
text	string	Required	The review text body.
id	string	Optional	Unique identifier for the review.
rating	integer	Optional	Reviewer’s rating. Scale: 0 to 10.
language	string	Optional	Language code for the review text (for example, `en`, `ja`, `de`).
created	string (date-time)	Optional	Date and time the review was created. Format: ISO 8601.
url	string (URL)	Optional	Link to the full review on the provider’s site.
user	User object	Optional	Information about the review author.

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.

Field	Type	Requirement	Description
id	string	Required	Unique identifier for the user.
name	string	Required	Display name of the user.
photoUrl	string (URL)	Optional	URL to the user’s profile photo.

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.

Field	Type	Requirement	Description
awardType	string	Optional	Category or type of award (for example, “Michelin Star”).
awardYear	string	Optional	Year the award was received (for example, “2025”).
awardName	string	Optional	Full name of the award.
awardSmallImage	string (URL)	Optional	URL to a small badge or logo image for the award.
awardLargeImage	string (URL)	Optional	URL to a large badge or logo image for the award.

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.

Field	Type	Requirement	Description
ranking	string	Optional	Human-readable ranking string (for example, “#4 of 13”).
rankingPosition	string	Optional	Numeric position in the ranking.
rankingDenominator	string	Optional	Total number of POIs in the ranking group.
rankingCategory	string	Optional	The category the POI is ranked within (for example, “Italian Restaurants”).
rankingGeo	string	Optional	Geographic location context for the ranking (for example, “Seattle, WA”).
rankingGeoId	string	Optional	Identifier for the ranking geography.

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.

Field	Type	Requirement	Description
chainIds	array of string	Optional	Identifiers for any chains this POI belongs to (for example, a franchise chain ID).
group	string	Optional	The broader business group this POI is affiliated with.
containedBy	string	Optional	The `id` of a parent POI that physically contains this POI (for example, a restaurant inside a shopping mall).
contains	array of string	Optional	Array of `id`s of POIs that are physically contained within this POI.

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.

Field	Type	Requirement	Description
knownFor	string	Optional	A short phrase describing what the business is best known for.
popularDishes	array of string	Optional	List of popular menu items (for food service POIs).
cuisine	object	Optional	Free-form key-value pairs describing cuisine type(s) offered (for example, `{"primary": "Italian"}`).
menu	object	Optional	Free-form key-value pairs describing menu and dietary options (for example, `{"vegetarian": "true", "glutenFree": "available"}`).
alcohol	object	Optional	Free-form key-value pairs describing alcohol service details (for example, `{"served": "Full Bar", "byo": "No"}`).
attire	object	Optional	Free-form key-value pairs describing dress code (for example, `{"required": "Smart Casual"}`).
goodFor	object	Optional	Free-form key-value pairs describing suitable-for designations (for example, `{"kids": "true", "groups": "true"}`).
capacity	object	Optional	Free-form key-value pairs describing seating or capacity information (for example, `{"seats": "120"}`).
amenities	object	Optional	Free-form key-value pairs describing available amenities (for example, `{"wifi": "Free", "outdoorSeating": "true"}`).
access	object	Optional	Free-form key-value pairs describing access restrictions (for example, `{"wheelchairAccessible": "true"}`).
parking	object	Optional	Free-form key-value pairs describing parking details (for example, `{"type": "Street", "free": "true"}`).
payment	object	Optional	Free-form key-value pairs describing accepted payment methods (for example, `{"creditCard": "true", "cash": "true"}`).
services	ServiceLists object	Optional	Structured service data (currently supports EV charging ports).
charging	object	Optional	EV charging summary attributes. Use `services.chargingPorts` for detailed port data.
events	object	Optional	Free-form key-value pairs describing events hosted at the POI.
hospital	object	Optional	Hospital-specific attributes (for healthcare POIs).
general	object	Optional	General business attributes not covered by other fields.
open24	object	Optional	24-hour operation indicators keyed by day or service type.

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.

Field	Type	Requirement	Description
chargingPorts	array of EVChargingPort	Optional	Individual EV charging port details.

EVChargingPort object

Represents a single EV charging port.

Field	Type	Requirement	Description
portId	string	Required	Unique identifier for this port.
ocpiIds	array of string	Optional	OCPI (Open Charge Point Interface) standard IDs for this port.
network	string	Optional	Charging network name (for example, “ChargePoint”, “Tesla”, “EVgo”).
name	string	Optional	Display name for this port.
costPerKwh	MonetaryValue	Optional	Cost per kilowatt-hour of energy delivered.
costPerMin	MonetaryValue	Optional	Cost per minute of charging time.
costPerUse	MonetaryValue	Optional	Flat fee per charging session.
free	boolean	Optional	Set to `true` if charging is provided at no cost.
chargingLevels	array of string	Optional	Charging levels available at this port (for example, `["LEVEL_2"]`, `["DC_FAST"]`).
connectorTypes	array of string	Optional	Connector type codes supported (for example, `["J_1772", "CHADEMO"]`).
connectors	array of EVConnector	Optional	Detailed connector-level data.

EVConnector object

Represents a specific charging connector.

Field	Type	Requirement	Description
connectorId	string	Required	Unique identifier for this connector.
ocpiId	string	Optional	OCPI standard ID for this connector.
connectorType	string	Optional	Connector type (for example, `J_1772`, `CHADEMO`, `TESLA`, `CCS`).
chargingLevel	string	Optional	Power delivery level: `LEVEL_1`, `LEVEL_2`, `LEVEL_3`, or `DC_FAST`.
volts	string	Optional	Voltage specification (for example, `"240"`).
kilowatts	string	Optional	Power output in kilowatts (for example, `"7.2"`).
amps	string	Optional	Amperage (for example, `"32"`).

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.

Field	Type	Requirement	Description
currencyCode	string	Required	ISO 4217 3-letter currency code (for example, `USD`, `EUR`, `GBP`). Regular expression pattern: `^[A-Z]{3}$`
value	string	Required	Decimal string representing the amount in the major currency unit. Regular expression pattern: `^[+-]?[0-9]*(\.[0-9]+)?$`

Example

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

ActionUrls object

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

Field	Type	Requirement	Description
providerUrl	string (URL)	Optional	The data provider’s listing page for this POI.
bookingUrl	string (URL)	Optional	Direct URL for reservations or appointment booking.
orderFoodUrl	string (URL)	Optional	Direct URL for online food ordering or delivery.
covidVaccineBookingUrl	string (URL)	Optional	URL for COVID-19 vaccine appointment booking.

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.

Field	Type	Requirement	Description
description	string	Required	The description text. Must be at least one character.
locale	string	Optional	BCP-47 locale code (for example, `en-US`). Regular expression pattern: `^[a-z]{2}-[A-Z]{2}$`

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

Type	Format	Example
Date-time (ISO 8601)	`yyyy-MM-ddTHH:mm:ssZ`	`2026-03-15T08:30:00Z`
Date only	`yyyy-MM-dd`	`2026-12-25`
Time only	`HH:mm:ss` (24-hour)	`09:00:00`, `22:30:00`

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}$

Valid	Invalid
`en-US`	`EN-US` (uppercase language)
`ja-JP`	`en_US` (underscore separator)
`de-DE`	`eng-US` (3-letter language code)

Country codes

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

Valid	Invalid
`US`	`us` (lowercase)
`GB`	`GBR` (3-letter code)
`DE`	`Germany` (full name)

Currency codes

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

Valid	Invalid
`USD`	`usd`
`EUR`	`US$`
`JPY`	`Dollar`

Monetary value

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

Valid	Invalid
`"1.50"`	`1.50` (must be a string)
`"45.00"`	`"$45.00"` (no currency symbol)
`"0.35"`	`"free"` (must be numeric)

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.

Create a Category Add-on Manually with the CLI

​Overview

​Submission format

​Requirement levels

​Submission rules

​Field requirements at a glance

​Top-level fields

​id

​name

​address

​location

​operatingInfo

​phone

​website

​categories

​alternateNames

​description

​media

​ratings

​relationships

​attributes

​priceRange

​costForTwo

​alexaSupportedActions

​actionUrls

​lastUpdated

​Object definitions

​Name object

​Address object

​Conditional rule for stateOrRegion

​Location object

​OperatingInfo object

​OperatingHours object

​SpecialHours object

​Media object

​Photo object

​Ratings object

​Review object

​User object

​Award object

​Ranking object

​Relationships object

​Attribute object

​ServiceLists object

​EVChargingPort object

​EVConnector object

​MonetaryValue object

​ActionUrls object

​Description object

​Format and validation rules

​Date and time formats

​Coordinate format

​URL format

​Locale codes

​Country codes

​Currency codes

​Monetary value

​Sample JSON data

​FAQs

​Related topics

Overview

Submission format

Requirement levels

Submission rules

Field requirements at a glance

Top-level fields

id

name

address

location

operatingInfo

phone

website

categories

alternateNames

description

media

ratings

relationships

attributes

priceRange

costForTwo

alexaSupportedActions

actionUrls

lastUpdated

Object definitions

Name object

Address object

Conditional rule for stateOrRegion

Location object

OperatingInfo object

OperatingHours object

SpecialHours object

Media object

Photo object

Ratings object

Review object

User object

Award object

Ranking object

Relationships object

Attribute object

ServiceLists object

EVChargingPort object

EVConnector object

MonetaryValue object

ActionUrls object

Description object

Format and validation rules

Date and time formats

Coordinate format

URL format

Locale codes

Country codes

Currency codes

Monetary value

Sample JSON data

FAQs

Related topics