API Docs

The TED API provides an easy to use RESTful interface with lightweight JSON or XML formatted responses to TEDTalks library and its associated data. In order to obtain the data during the private beta period you must qualify for the API key through the TED API-50 open call. This documentation serves as a starting point for developers interested in participating in the contest to better understand different types of data set we are making available.

General format

TED API has one entry point:http://api.ted.com and a version number appended to the entry point. 

A resource is an entity that can be requested as a collection or one at a time. At the top-most level, you can obtain these sets of resources. Click on individual resource to see detailed documentation.

 

• Talks  (as talks)
• Events (as events)
• Languages (as languages)
• Quotes (as quotes)
• Rating Words
• Speakers (as speakers)
• Tags (as tags)
• Themes (as themes)
• Countries (as countries)

Standard parameters

Parameter	Type	Description
api-key	string	Currently required for all api calls.
fields	string	Some requests come with additional fields or collections to request. to add the to the response, use: fields=field1,field2,collection1
filter	string	Exact match, wildcard match, greater than/less than match, range match. Filters may be applied to date, integer, and string fields. You can combine any number of these filters by separating them with a comma. Note: not every combination will work and the more you add the more you run the risk of returning no results. there is currently no way to perform a boolean OR with these filters.
language	string	For resources that support it (talks and subtitles), you can supply a language parameter to change the language returned. Defaults to ‘en’ for english.
limit	integer	Use limit and offset to control result set sizes as they return to you. example: /v1/talks.json?limit=100&offset=50 Note: base developer keys are limited to requesting page sizes of 100.
offset	integer	Use limit and offset to control result set sizes as they return to you. example: /v1/talks.json?limit=100&offset=50 Note: base developer keys are limited to requesting page sizes of 100.
order	string	Allows for ordering of results. Possible values include asc|desc example: order=created_at:asc
sort	string	sort allows you to sort by specific, more advanced, custom criteria. example: sort=popular Note: this parameter is only available for a limited number of requests.
suppress_error_codes	boolean	In order to force a HTTP 200 response, append this to your request: example: suppress_error_codes=true response contents will still contain the correct error code.

Example API calls:

Retrieve speaker information where speaker's first name is 'Michael':
Retrieve speaker information where speaker's last name starts with the letter "A":
Retrieve talks with id greater than 350:
Retrieve talks with id greater than 350 using the Japanese language:
Retrieve talks with id in the range 1300 to 1400 inclusive:

Available Resources

Events

Available fields for Events

Field	Description
id	Unique identifier for this resource
name	The name of this resource
description	A text description of this resource
header_text	For internal purposes
slug	The text slug for this resource
url	The official url for this event
starts_at	The start date for this event
ends_at	The end date for this event

Additional collections or attributes

• speakers

Request format:

Languages

Available fields for Languages

Field	Description
name	The name of this resource
description	A text description of this resource
language_code	The text code for this language

Request format:

Quotes

Available fields for Quote

Field	Description
id	Unique identifier for this resource
talk_id	The Id for the talk associated with this quote
speaker_id	The Id for the speaker associated with this quote
slug	The text slug for this resource
quote	The text representation of this quote
count	Number of times this quote has been shared
context	Context information for this quote
created_at	The date this resource was created
updated_at	The date this resource was updated

Request format:

Rating Words

Available fields for Rating Words

Field	Description
id	Unique identifier for this resource
name	The name of this resource

Request format:

Speakers

Available fields for Speakers

Field	Description
id	Unique identifier for this resource
title	Professional title for this speaker
firstname	First name of the speaker
middleinitial	Middle initial of the speaker
lastname	Last name of the speaker
description	A text description of this resource
whotheyare	Brief text description/bio of this speaker
whylisten	A longer topical text description of this speaker
slug	The text slug for this resource
published_at	Date this information was published

Additional collections or attributes

• photo_url
• talks

Request format:

Tags module

Available fields for Tag

Field	Description
id	Unique identifier for this resource Note: although the tag id is provided, you should never use this to establish relationships to other entities. Instead, use the name as it is the canonical identifier.
name	The name of this resource

Request format:

Themes

Available fields for Themes

Field	Description
id	Unique identifier for this resource
name	The name of this resource
description	A text description of this resource
shortsummary	A short text summary for this theme
talks_description	Text description of the talks associated with this theme
speakers_description	Text description for the speakers associated with this theme
slug	The text slug for this resource
is_featured	Boolean flag, set to true if this theme is featured on ted.com

Additional collections or attributes

• photo_url
• related_talks

Request format:

Talks

Available fields for Talks

Field	Description
id	Unique identifier for this resource
event_id	The Id for the event associated with this talk
slug	Text slug for this talk
native_language_code	Language code for this talk
published_at	Date this talk was published
recorded_at	Date this talk was recorded
updated_at	Date this talk was last updated

Additional collections or attributes

• name
• description
• events
• media
• next_talks_ids
• media_profile_uris
• photo_urls
• rating_word_ids
• speaker_ids
• speakers
• theme_ids
• tags

Additional parameters

name	string	Search for talks by name, with wildcards example: /v1/talks.json?api-key=YOURKEYHERE&name=*climate*
externals	boolean	Indicates whether or not talks with external media should be included or not (youtube, vimeo) example: /v1/talks.json?api-key=YOURKEYHERE&externals=true
podcasts	boolean	Include only those talks with podcasts example: /v1/talks.json?api-key=YOURKEYHERE&podcasts=true

Request format:

Extended Requests

• https://api.ted.com/v1/talks/:id/subtitles.json?api-key=YOURKEYHERE
• https://api.ted.com/v1/talks/:id/speakers.json?api-key=YOURKEYHERE

Countries

Available fields for Countries

Field	Description
id	Unique identifier for this resource Note: although the tag id is provided, you should never use this to establish relationships to other entities. Instead, use the name as it is the canonical identifier.
name	The name of this resource
code	Abbreviated country code for the country

Request format: