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

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 /entities/v1/{entity-id}

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

Copied to clipboard.

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

entity-id

Path

Unique ID of the entity.
Found in intent.slots.SlotName.resolutions.resolutionsPerAuthority[].values[].value.id.
There might be multiple entities for a slot value. The values array includes the entities in order of relevance, with the most relevant first. You can call the Entity lookup operation again for each entity to get more information to further disambiguate the utterance.

String

Yes

access token

Header

Access token for the customer.
Set to request.context.System.apiAccessToken property from the IntentRequest.

String

Yes

locale

Header

Locale for localized strings in the response.
The API doesn't consider the locale of the skill request. For example, for an en-US skill, if you set locale to es-MX, the API returns Spanish strings.

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

@context

Defines linked data rules for the document.

JSON-LD context object

@id

(Optional) Identifies the endpoint and entity.
Formatted as an IRI.

String

@type

Specifies the class of the entity, such as Book or Person. The entity class determines the set of properties available. For more details about the properties for an entity class, see Alexa Entities Reference.

Array of strings

name

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

rdf:langString

Entity properties

Remaining properties are specific to the entity class (@type). For example, a Person entity might have the birthplace and birthdate properties.

Various

HTTP status codes

Status Description

200 OK

Response body contains data properties of the specified entity.

204 No Content

Entity exists but no data properties are defined.

400 Bad Request

Indicates that one or more properties in the request body aren't valid.
The following example shows the response body with the error code and message.

{
     "message": "The property is outside the allowed range.",
     "code": "INVALID_STRING_LENGTH"
}

401 Unauthorized

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.

403 Forbidden

Indicates that the authorization token is valid, but the requested operation isn't allowed.

404 Not Found

Requested resource not found.

429 Too Many Requests

Permitted rate limit, specified as number of requests per unit of time, exceeded. Retry the request by using exponential back-off.

500 Server Error

Error occurred on the server. Retry the request by using exponential back-off.

503 Service Unavailable

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

ar-SA

Arabic (SA)

de-DE

German (DE)

en-AU

English (AU)

en-CA

English (CA)

en-GB

English (UK)

en-IN

English (IN)

en-US

English (US)

es-ES

Spanish (ES)

es-MX

Spanish (MX)

es-US

Spanish (US)

fr-CA

French (CA)

fr-FR

French (FR)

hi-IN

Hindi (IN)

it-IT

Italian (IT)

ja-JP

Japanese (JP)

nl-NL

Dutch (NL)

pt-BR

Portuguese (BR)

Sample code

The following sample code demonstrates how to build a skill that uses the Linked Data API:


Was this page helpful?

Last updated: Aug 01, 2024