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.

 

To access a resource as a collection:

 

/v1/:resource.:format

 

Example: /v1/talks.json or /v1/talks.xml

To access resource as a single entity:

 

/v1/:resource/:id.:format

 

Where :id = the id# of the record in question (this is usually obtained through calls to the collection).

Example: /v1/talks/1.json

Standard parameters

ParameterTypeDescription
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':
http://api.ted.com/v1/speakers.json?api-key=YOURKEYHERE&filter=firstname:Michael

Retrieve speaker information where speaker's last name starts with the letter "A":
http://api.ted.com/v1/speakers.json?api-key=YOURKEYHERE&filter=lastname:a*

Retrieve talks with id greater than 350:
http://api.ted.com/v1/talks.json?api-key=YOUKEYHERE&filter=id:>350

Retrieve talks with id greater than 350 using the Japanese language:
http://api.ted.com/v1/talks.json?api-key=YOUKEYHERE&filter=id:>350&language=ja

Retrieve talks with id in the range 1300 to 1400 inclusive:
http://api.ted.com/v1/talks.json?api-key=YOURKEYHERE&filter=id:1300..1400

Available Resources

Events

Available fields for Events
FieldDescription
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:
https://api.ted.com/v1/events.json?api-key=YOURKEYHERE https://api.ted.com/v1/events/1.json?api-key=YOURKEYHERE

Languages

Available fields for Languages
FieldDescription
name The name of this resource
description A text description of this resource
language_code The text code for this language
Request format:
https://api.ted.com/v1/languages.json?api-key=YOURKEYHERE https://api.ted.com/v1/languages/1.json?api-key=YOURKEYHERE

Quotes

Available fields for Quote
FieldDescription
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:
https://api.ted.com/v1/quotes.json?api-key=YOURKEYHERE https://api.ted.com/v1/quotes/1.json?api-key=YOURKEYHERE

Rating Words

Available fields for Rating Words
FieldDescription
id Unique identifier for this resource
name The name of this resource
Request format:
https://api.ted.com/v1/rating_words.json?api-key=YOURKEYHERE https://api.ted.com/v1/rating_words/1.json?api-key=YOURKEYHERE

Speakers

Available fields for Speakers
FieldDescription
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:
https://api.ted.com/v1/speakers.json?api-key=YOURKEYHERE
https://api.ted.com/v1/speakers/1.json?api-key=YOURKEYHERE

Tags module

Available fields for Tag
FieldDescription
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:
https://api.ted.com/v1/tags.json?api-key=YOURKEYHERE
https://api.ted.com/v1/tags/1.json?api-key=YOURKEYHERE

Themes

Available fields for Themes
FieldDescription
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:
https://api.ted.com/v1/themes.json?api-key=YOURKEYHERE https://api.ted.com/v1/themes/1.json?api-key=YOURKEYHERE

Talks

Available fields for Talks
FieldDescription
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:
https://api.ted.com/v1/talks.json?api-key=YOURKEYHERE https://api.ted.com/v1/talks/1.json?api-key=YOURKEYHERE

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:
https://api.ted.com/v1/countries.json?api-key=YOURKEYHERE
https://api.ted.com/v1/countries/1.json?api-key=YOURKEYHERE