ViewChange.org
VIDEOS
TOPICS

API Reference (v1)

API response format will be determined by the extension used in the API call. For example, the following URL will return JSON data:

http://api.viewchange.org/v1/videos.json

Valid response formats:
  • .xml
  • .json

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 entities)
      • 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)

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)
Powered By