Linked Data API Reference

Use the Linked Data API to retrieve information about the Alexa entities that your skill users ask about. An entity represents a real-world person, place, or thing. Built-in slot types that support entity resolution disambiguate user utterances into specific, known entities. You use the Linked Data API to retrieve details about the entity from the Alexa knowledge graph.

For example, the user might say the value "holland" to fill a slot that uses the built-in slot type AMAZON.Country. Alexa resolves "holland" to the entity "Netherlands," so the IntentRequest includes a unique entity identifier that points to the Netherlands in the knowledge graph. You call the Linked Data API with this identifier to retrieve information about the country, such as its population. You can then use that information in your skill response.

You can use Alexa Entities in the following locales:

  • English (AU)

  • English (CA)

  • English (IN)

  • English (UK)

  • English (US)

  • French (FR)

  • German (DE)

  • Italian (IT)

  • Spanish (ES)

API endpoint

To call the Linked Data API, you send a request to an internationalized URI (IRI). The IRI is both the API endpoint and the identifier for the entity in the knowledge graph. Retrieve the full IRI for an entity from the IntentRequest sent to your skill. For more details about when a skill request includes IRIs, see Retrieve the IRI from the skill request.

The following example shows an IRI for an Alexa entity.

https://ld.amazonalexa.com/entities/v1/6ZmdJgzS4ipuScmQo0ppz4

This endpoint is different from the api.amazonalexa.com endpoint typically used for Alexa APIs. The Linked Data API uses the IRI provided in the skill request instead.

Entity lookup request

The entity lookup request retrieves the specified entity from the Alexa knowledge graph.

GET https://ld.amazonalexa.com/entities/v1/{string}

Retrieve the full IRI from the skill request and use it in your GET request. For example, the IRI in the skill request might be https://ld.amazonalexa.com/entities/v1/6ZmdJgzS4ipuScmQo0ppz4. For more details about when a skill request includes IRIs, see Retrieve the IRI from the skill request.

The request doesn't have a request body.

Header of the request

Authorization: Bearer <<apiAccessToken>>
Accept-Language: <<locale, for example en-US>>
Accept: application/ld+json

Authorization header

Each API request must have an Authorization header. Set this header to the apiAccessToken provided in the context.System.apiAccessToken property in the skill request.

In the following example request, the apiAccessToken begins with AxThk. Provide the full token in the Authorization header in the format: Bearer ACCESS_TOKEN, where ACCESS_TOKEN is the value of the apiAccessToken field from the Alexa request message.

{
  "version": "1.0",
  "session": {},
  "context": {
    "System": {
      "application": {
        "applicationId": "amzn1.ask.skill.1"
      },
      "user": {
        "userId": "amzn1.ask.account.AH"
      },
      "device": {
        "deviceId": "amzn1.ask.device.AGL",
        "supportedInterfaces": {
          "Alexa.Presentation.APL": {
            "runtime": {
              "maxVersion": "2023.1"
            }
          }
        }
      },
      "apiEndpoint": "https://api.amazonalexa.com",
      "apiAccessToken": "AxThk..."
    },
    "Viewport": {},
    "Viewports": []
  },
  "request": {}
}

Accept-Language header

The Linked Data API uses the Accept-Language header to determine the locale for any localized strings in the response. Set this header to the locale that you want for your response. The API doesn't consider the locale of the skill request. For example, for an en-US skill, if you set Accept-Language to es-MX, the API returns Spanish strings.

The Accept-Language header is required.

Retrieve the IRI from the skill request

An IntentRequest sent to your skill includes an IRI for an Alexa entity in the following scenario:

  1. Your interaction model has a custom intent that uses a built-in slot type that supports entity resolution. Not all built-in types support entity resolution. For a list, see the Alexa Entities Reference.
  2. When the user invokes the intent, their utterance for the slot is a value that Alexa resolves to a known entity or entities in the knowledge graph.

When the user's utterance resolves to a known entity, the IRI for the entity is available in the resolutions.resolutionsPerAuthority[].values[].value.id property. Within the resolutionsPerAuthority array, the authority is "AlexaEntities".

{
  "version": "1.0",
  "session": {},
  "context": {},
  "request": {
    "type": "IntentRequest",
    "requestId": "amzn1.echo-api.request.1",
    "locale": "en-US",
    "timestamp": "2021-01-15T22:49:26Z",
    "intent": {
      "name": "WhoIsIntent",
      "confirmationStatus": "NONE",
      "slots": {
        "Person": {
          "name": "Person",
          "value": "bezos",
          "resolutions": {
            "resolutionsPerAuthority": [
              {
                "authority": "AlexaEntities",
                "status": {
                  "code": "ER_SUCCESS_MATCH"
                },
                "values": [
                  {
                    "value": {
                      "name": "Jeff Bezos",
                      "id": "https://ld.amazonalexa.com/entities/v1/6ZmdJgzS4ipuScmQo0ppz4"
                    }
                  },
                  {
                    "value": {
                      "name": "Mackenzie Bezos",
                      "id": "https://ld.amazonalexa.com/entities/v1/4r51itmsh0aQsz2yyVVEER"
                    }
                  },
                  {
                    "value": {
                      "name": "Yannis Bezos",
                      "id": "https://ld.amazonalexa.com/entities/v1/z0fYLagm4L0X3deptSiodB"
                    }
                  },
                  {
                    "value": {
                      "name": "Mike Bezos",
                      "id": "https://ld.amazonalexa.com/entities/v1/F9GKAu5mLT4iPP5d5xRetG"
                    }
                  },
                  {
                    "value": {
                      "name": "Mark Bezos",
                      "id": "https://ld.amazonalexa.com/entities/v1/fQxk1G8jtN4F7fe1NntcCH"
                    }
                  }
                ]
              }
            ]
          },
          "confirmationStatus": "NONE",
          "source": "USER",
          "slotValue": {
            "type": "Simple",
            "value": "bezos",
            "resolutions": {
              "resolutionsPerAuthority": [
                {
                  "authority": "AlexaEntities",
                  "status": {
                    "code": "ER_SUCCESS_MATCH"
                  },
                  "values": [
                    {
                      "value": {
                        "name": "Jeff Bezos",
                        "id": "https://ld.amazonalexa.com/entities/v1/6ZmdJgzS4ipuScmQo0ppz4"
                      }
                    },
                    {
                      "value": {
                        "name": "Mackenzie Bezos",
                        "id": "https://ld.amazonalexa.com/entities/v1/4r51itmsh0aQsz2yyVVEER"
                      }
                    },
                    {
                      "value": {
                        "name": "Yannis Bezos",
                        "id": "https://ld.amazonalexa.com/entities/v1/z0fYLagm4L0X3deptSiodB"
                      }
                    },
                    {
                      "value": {
                        "name": "Mike Bezos",
                        "id": "https://ld.amazonalexa.com/entities/v1/F9GKAu5mLT4iPP5d5xRetG"
                      }
                    },
                    {
                      "value": {
                        "name": "Mark Bezos",
                        "id": "https://ld.amazonalexa.com/entities/v1/fQxk1G8jtN4F7fe1NntcCH"
                      }
                    }
                  ]
                }
              ]
            }
          }
        }
      }
    }
  }
}

There might be multiple possible entities for a particular slot value. The possible entities are listed in order of relevance, with the most relevant first. You can call the Linked Data API again with the different entities to get more information to further disambiguate the user's utterance.

For more about entity resolution, see the following:

Entity lookup response

The API response returns data from the Alexa knowledge graph relevant to the entity. The type of data that appears in the response depends on the entity type and the data available in the Alexa knowledge graph for the entity. For example, a Person entity might include properties for birthdate and birthplace. For details about the entity types and possible properties, see Alexa Entities Reference.

Header of the response

X-Amzn-RequestId: abcd...
Content-Language: <<locale, for example en-US>>
Content-Type: application/ld+json

Response body

The response body uses JSON-LD syntax, which is a format intended for linked data. For more details about the response format and JSON-LD, see Alexa entities and JSON-LD syntax.

The following example illustrates the response body.

You access the data in the response as normal JSON. You don't need JSON-LD specific libraries or tools. However, because JSON-LD uses the @ sign in property names that represent reserved keywords, use bracket notation instead of dot notation to access the keyword properties. For example, to access properties from the earlier example, use the following bracket notation.

name[0]['@value'] // returns "Canada" (the first name value in the array)
politicalLeader[0].name[0]['@value'] // returns Justin Trudeau

Top-level properties

The response represents a node in a knowledge graph, from which you can link to other entities by calling the Linked Data API again. The response includes the top-level properties defined in the following table.

Name Description Type Required

@context

Defines JSON-LD rules for the document.

JSON-LD context object

Yes

@id

An IRI that identifies the entity. Use this IRI to call the Entity Lookup API to retrieve data about the entity.

String

No

@type

Specifies the class of the entity, such as Book or Person. The entity class determines the set of properties available.

Array of strings

Yes

name

A label for the entity that provides the human-friendly name and language. Multiple names might be returned. See Data properties.

rdf:langString

No

The remaining top-level properties are specific to the entity class (@type). For example, a Person entity might have the birthplace and birthdate properties.

For details about the specific properties available for each entity class, see the Alexa Entities Reference.

When a user begins a new session with your skill, call the Linked Data API to retrieve the most recent data from the knowledge graph. Don't cache and reuse the data across different skill sessions.

Error codes

Status code Name Description
200 OK The request succeeded. Retrieve the result of the request in the body and the headers of the response.
204 No Content The entity identified by the specified ID exists but has no data.
401 Unauthorized The authentication token is invalid or doesn't have access to the resource.
403 Forbidden Client isn't authorized to access the resource.
404 Not Found Unknown entity.
429 Too Many Requests Too many requests.
500 Internal Server Error Unexpected server-side failure.

Linked Data API Code Sample

For complete code samples that demonstrate the Linked Data API and Alexa Entities, see the following:

Last updated: Mar 30, 2022