Skip to content

Platform API Reference

Jump to bottom
robdiciuccio edited this page May 31, 2011 · 2 revisions

The platform API is not enabled by default. To enable, set enable_api to true, in the configuration.

The platform API supports both JSON and XML responses. Response format will be determined by the extension used in the API call. For example, the following URL will return JSON data:

/api/v1/videos.json

Valid response formats/extensions:

  • .json
  • .xml

Global API parameters

Parameters sent with all API calls

  • page (integer, optional)
  • Default: 1
  • page_size (integer, optional)
  • Results per page. Default: 16

Global API response values

Returned with all API responses

  • status (object)
  • text (string, possible values: "OK", "FAIL")
  • message (string, descriptive status message)
  • response_time (date)
  • sort (string, if present in request and status=OK)
  • paging (object, present only if status=OK)
  • page (integer)
  • pages (integer)
  • page_size (integer)
  • total_items (integer)

Response objects

Topic

  • topic (object)
  • id (integer)
  • name (string)
  • url (string)
  • description (string)
  • entities (list of Linked Data Entity objects)

Entity

  • entity (object)
  • url (string)
  • name (string)
  • source (string)

Video

  • video (object)
  • id (integer)
  • name (string)
  • url (string)
  • duration (integer)
  • description (string)
  • publish_date (date YYYY-MM-DD HH:SS)
  • thumbnail_url (string, width: 100px)
  • thumbnail_url_lg (string, width: 480px)
  • embed_code (string, HTML)
  • transcript_text (string, returned only if return_transcript='true')
  • topics (list of related Topic objects, returned only if return_topics='true')
  • chapters (list of Chapter objects, returned only if return_chapters='true')

Video Chapter

  • chapter (object)
  • id (integer)
  • name (string)
  • start_time (integer)
  • thumbnail_url (string, 75px)
  • thumbnail_url_lg (string, 400px)
  • transcript_text (string, returned only if return_transcript='true')

Region

  • region (object)
  • id (integer)
  • name (string)

API Endpoints

GET /topics

Return topic data

Parameters (optional)

  • featured (string)
  • Return only featured topics. Possible values: "true", "false" (default: "false")
  • sort (string)
  • Possible values: "alpha", "newest", "popular" (default: "alpha")

Response

  • topics (list of Topic objects)

GET /topics/:id

Return topic data for a specified topic

Parameters (optional)

Response

  • topic (Topic object)

GET /topics/search

Return topics that match the text query.

Parameters (required)

  • q (string)

Parameters (optional)

  • sort (string)
  • Possible values: "relevance", "alpha", "newest", "popular" (default: "relevance")

Response

  • topics (list of Topic objects)

GET /regions

Return region data (no additional parameters)

Response

  • regions (list of Region objects)

GET /regions/:id

Return region data for specified region (no additional parameters)

Response

  • region (Region object)

GET /videos

Return video data

Parameters (optional)

  • featured (string)
  • Return only featured videos. Possible values: "true", "false" (default: "false")
  • topics (list of topic IDs, comma separated)
  • Each topic ID passed will narrow the result set (eg. "Water" AND "Education"). If no topics are passed, all videos will be returned.
  • regions (list of region IDs, comma separated)
  • Each region ID passed will narrow the result set (eg. "Africa" AND "Asia"). If no regions are passed, all videos will be returned.
  • sort (string)
  • Possible values: "relevance", "alpha", "newest" (default: "relevance")
  • return_topics (string)
  • Possible values: "true", "false" (default: "false")
  • return_transcript (string)
  • Possible values: "true", "false" (default: "false")
  • return_chapters (string)
  • Possible values: "true", "false" (default: "false")

Response

  • videos (list of Video objects)

GET /videos/:id

Return video data for a specified video

Parameters (optional)

  • return_topics (string)
  • Possible values: "true", "false" (default: "false")
  • return_transcript (string)
  • Possible values: "true", "false" (default: "false")
  • return_chapters (string)
  • Possible values: "true", "false" (default: "false")

Response

  • video (Video object)

GET /videos/search

Return video IDs based on search query

Parameters (required)

  • q (string)

Parameters (optional)

  • sort (string)
  • Possible values: "relevance", "alpha", "newest", "popular" (default: "relevance")

Response

  • videos (list of Video objects)
Clone this wiki locally