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.3"
}
}
}
},
"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:
- 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.
- 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"
}
}
]
}
]
}
}
}
}
}
}
}
value
and resolutions
properties directly on the slot object are provided for backward compatibility. The preferred way to access slot values in the request is with the slotValue
property. This property is available for slots that collect a single value and slots that collect multiple values.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 |
---|---|---|---|
|
Defines JSON-LD rules for the document. |
JSON-LD context object |
Yes |
|
An IRI that identifies the entity. Use this IRI to call the Entity Lookup API to retrieve data about the entity. |
String |
No |
|
Specifies the class of the entity, such as |
Array of strings |
Yes |
|
A label for the entity that provides the human-friendly name and language. Multiple names might be returned. See Data properties. |
|
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. |
Sample code
The following sample code demonstrates how to build a skill that uses the Linked Data API:
Related topics
Last updated: Nov 28, 2023