Linked Data REST API Reference
Use the Linked Data REST API to retrieve information about 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. 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" and includes the entity identifier in the IntentRequest
. You use the Linked Data API to retrieve details about the entity, such as capital and population. You can then use these details in your skill response.
For more details about Alexa entities, see Entity Resolution.
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
The endpoint of the Linked Data API is an Internationalized Resource Identifier (IRI) from the IntentRequest
when the Alexa resolves the user utterance to a known entity or entities. The IRI is both the API endpoint and the identifier for the entity in the knowledge graph.
For more details about the IRI, see RFC 3987.
The following example shows an IRI for an Alexa entity. The endpoint is ld.amazonalexa.com
and the entity ID is 6ZmdJgzS4ipuScmQo0ppz4
.
https://ld.amazonalexa.com/entities/v1/6ZmdJgzS4ipuScmQo0ppz4
api.amazonalexa.com
endpoint typically used for Alexa REST APIs. The Linked Data API uses the IRI provided in the skill request instead.Authentication
Each API request must have an authorization header whose value is the context.System.apiAccessToken
retrieved from an IntentRequest
request from Alexa.
Operations
The Linked Data API includes the following operations.
Operation | HTTP method and URI |
---|---|
|
Entity lookup
Get the properties of the specified entity.
Request
To get the entity, you make a GET
request to the /entities/v1
resource.
Request path and header example
GET /entities/v1/{entity-id}
Host: https://ld.amazonalexa.com
Content-Type: application/json
Authorization: Bearer {access token}
Accept-Language: {locale}
Accept: application/ld+json
Request path and header parameters
Parameter | Located in | Description | Type | Required |
---|---|---|---|---|
|
Path |
Unique ID of the entity. |
String |
Yes |
|
Header |
Access token for the customer. |
String |
Yes |
|
Header |
Locale for localized strings in the response. |
String |
Yes |
Request body example
The request has no body.
Request body properties
The request has no body.
Response
If the specified entity exists and has data, and the request succeeds, the response returns HTTP 200 OK
, along with the specified entity properties. If the specified entity exists but doesn't have data, and the request succeeds, the response returns HTTP 204 No Content
.
On error, the response returns the appropriate HTTP status code and includes a response body with an error code and human readable message.
Response body example
Response body properties
The response body uses the JSON-LD format for linked data.
Access the data in the response as normal JSON. You don't need JSON-LD specific libraries or tools. However, JSON-LD uses the @
sign in property names that represent reserved keywords. Here, use bracket notation instead of dot notation to access the keyword properties.
For more details about the response format and JSON-LD, see Alexa entities and JSON-LD syntax.
The following example shows how to use bracket notation.
name[0]['@value'] // returns "Canada" (the first name value in the array)
politicalLeader[0].name[0]['@value'] // returns Justin Trudeau
Property | Description | Type |
---|---|---|
|
Defines linked data rules for the document. |
JSON-LD context object |
|
(Optional) Identifies the endpoint and entity. |
String |
|
Specifies the class of the entity, such as |
Array of strings |
|
(Optional) Label for the entity that provides the localized human-friendly name and language. The response might contain multiple names. For more details, see Data properties. |
|
Entity properties |
Remaining properties are specific to the entity class ( |
Various |
HTTP status codes
Status | Description |
---|---|
|
Response body contains data properties of the specified entity. |
|
Entity exists but no data properties are defined. |
|
Indicates that one or more properties in the request body aren't valid.
|
|
Request didn't include the authorization token, or the included token expired or isn't valid. Or, you don't have access to the resource. |
|
Indicates that the authorization token is valid, but the requested operation isn't allowed. |
|
Requested resource not found. |
|
Permitted rate limit, specified as number of requests per unit of time, exceeded. Retry the request by using exponential back-off. |
|
Error occurred on the server. Retry the request by using exponential back-off. |
|
Server is down for maintenance, overloaded, or otherwise unavailable to handle the incoming request. |
Object definitions
The Linked Data API defines the following object definitions.
Locale values
The following table shows valid values for the locale
property.
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)
Locale code | Language |
---|---|
|
Arabic (SA) |
|
German (DE) |
|
English (AU) |
|
English (CA) |
|
English (UK) |
|
English (IN) |
|
English (US) |
|
Spanish (ES) |
|
Spanish (MX) |
|
Spanish (US) |
|
French (CA) |
|
French (FR) |
|
Hindi (IN) |
|
Italian (IT) |
|
Japanese (JP) |
|
Dutch (NL) |
|
Portuguese (BR) |
Sample code
The following sample code demonstrates how to build a skill that uses the Linked Data API:
Related topics
Last updated: Aug 01, 2024