Linked Data REST API Reference

Note: Sign in to the developer console to build or publish your skill.

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

Important: This endpoint is different from the 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 /entities/v1/{entity-id}`

Entity lookup

Get the properties of the specified entity.

Important: When a user begins a new session with your skill, call the Entity lookup operation to get the most recent data from Alexa. Don't cache and reuse data across skill sessions.

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

{
  "@context": {
    "@vocab": "https://schema.amazonalexa.com/core/1.0/",
    "@type": {
      "@id": "type",
      "@container": "@set"
    },
    "borderingCountry": {
      "@id": "https://schema.amazonalexa.com/core/1.0/borderingCountry",
      "@container": "@set"
    },
    "capital": {
      "@id": "https://schema.amazonalexa.com/core/1.0/capital",
      "@container": "@set"
    },
    "currency": {
      "@id": "https://schema.amazonalexa.com/core/1.0/currency",
      "@container": "@set"
    },
    "humanPopulation": {
      "@id": "https://schema.amazonalexa.com/core/1.0/humanPopulation",
      "@container": "@set"
    },
    "name": {
      "@id": "https://schema.amazonalexa.com/core/1.0/name",
      "@container": "@set"
    },
    "politicalLeader": {
      "@id": "https://schema.amazonalexa.com/core/1.0/politicalLeader",
      "@container": "@set"
    },
    "xsd": "http://www.w3.org/2001/XMLSchema#"
  },
  "@id": "https://ld.amazonalexa.com/entities/v1/KergWGkJmd9FT9YSvzn3AL",
  "@type": [
    "Country"
  ],
  "borderingCountry": [
    {
      "@id": "https://ld.amazonalexa.com/entities/v1/AJGFaH8FpvdBHPuUlYi9rX",
      "@type": [
        "Country"
      ],
      "name": [
        {
          "@language": "en",
          "@value": "United States"
        }
      ]
    }
  ],
  "capital": [
    {
      "@id": "https://ld.amazonalexa.com/entities/v1/4UReWIgsWRxD1BJaIUA2Ad",
      "@type": [
        "City"
      ],
      "name": [
        {
          "@language": "en",
          "@value": "Ottawa"
        }
      ]
    }
  ],
  "currency": [
    {
      "@type": [
        "Currency"
      ],
      "name": [
        {
          "@language": "en",
          "@value": "Canadian dollar"
        }
      ]
    }
  ],
  "humanPopulation": [
    {
      "@type": "xsd:integer",
      "@value": "37700000"
    }
  ],
  "name": [
    {
      "@language": "en",
      "@value": "Canada"
    }
  ],
  "politicalLeader": [
    {
      "@id": "https://ld.amazonalexa.com/entities/v1/4v7JvEnQrCSDpwtl6qA05A",
      "@type": [
        "Person"
      ],
      "name": [
        {
          "@language": "en",
          "@value": "Justin Trudeau"
        }
      ]
    }
  ]
}

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.