OpenCourseWare Search API from OCW Search
The OCW Search API described on this page gives you access to the full OCW Search index programmatically.
API Documentation - Basics
The API is designed to be very simple to use. You construct a URL that you retrieve the contents of, and it returns a JSON output of the search results.
The API is versioned, meaning that each API endpoint specifies the version number. This maintains backwards compatability in that when the API gets updated in a way that would break the default behavior, it gets a new version number, and your application will not break.
The API outputs only JSON. Support for XML responses are not planned unless there is significant demand for it. See the Mailing List and Getting Help section below for contact details.
Currently the API does not support JSONP but this is a planned top priority. JSONP will allow you to use the API in web browsers as it is a secure mechanism to do cross-domain scripting.
API Endpoint
The API endpoint is of this format:
http://www.ocwsearch.com/api/vX/search.json?q=QUERY&page=PAGE&contact=CONTACT
In detail:
- vX is the version of the API. Currently it is v1. This is part of the URL so it is required.
- QUERY is a URL-encoded search term. This is required if you want results; otherwise you will get an empty JSON object back., which is just a waste of resources. The API fully supports all Advanced Search Queries.
- PAGE is the page number of the results you wish to retrieve. This is optional.
- CONTACT is a URL of a web page describing your application and listing a way we can contact you. This is required.
For example, to search for the word "statistics", the URL of the results is:
Both QUERY and CONTACT must be URL-encoded. PAGE is always a number, so it does not matter, but QUERY and CONTACT is text and must be. If you do not URL encode, it is likely you will see some API calls fail.
JSON Response
The JSON response is divided into three sections:
- General section, which lists details of the search. Currently, these are:
- ResultsStart: the index of the first result. It is zero-based (i.e. the first page will start at zero).
- ResultsEnd: The index of the last result returned. On the first page, that would be 20, on the second page 40, and so on.
- TotalCount: The total number of results found in the OCW Search index.
- Page: Which page the response is for.
Together, these allow you to tell the user something like "Results 21-40 of 780" - Pages array: This is a list of API endpoints for each page of the results set for your convenience.
- Results array: These are the results numbered 1 to 20. The API always returns up to 20 results, and this is not changeable at this time. Each result has the following details:
- Title: The title of course. If known, the course number will be prefixed to the title.
- Description: The official course description as given by the university.
- Instructors: The people listed as teaching the course.
- TeachingDate: When the course was taught as given by the university. This is not in a standard format because each university gives teaching dates differently.
- CourseURL: The URL of the home page of the course.
- Institution: A shortened name of the institution teaching this course. For example, "nd" is Notre Dame. For a full list, see the Institution Search in the Search Help page.
- CourseSection: The department within the institution offering this course. For courses cross-listed across multiple departments, this will be the main department that is actually offering it.
- DownloadPageLink: The URL to the page with the download link of the course materials.
- DownloadPageAnchorText: This is the anchor text given by the university to the download page. We use it to maintain consistency in what the institutions call this link and OCW Search.
Very important point: all courses will have at least the title, the description, and the URL. However, any of the remaining fields may be missing because the institution does not share it readily, if at all. The most likely field to be missing is the teaching date, but there are examples of other fields missing. When a field is unknown, it will be returned as an empty string.
Caching
Please implement results caching in your web application if possible. OCW Search index updates occur only once every 1-3 weeks and so the results for a query will not change in the meantime.
Rate Limiting
At the moment there isn't a hard rate limiter in place, but the API usage is monitored. Heavy users will be contacted (that is why we need the contact details in each API call), and abusers will be banned out-right.
Debugging
As the API output is JSON, any JSON-aware debugging tool will work. Here is a selection:
Mailing List and Getting Help
For contacting us privately, please email apicontact (at) ocwsearch (dot) com.
We also maintain a mailing list for anyone using or interested in the API. You can subscribe using this form:
The mailing list is for pretty much anything API related:
- Getting help and asking questions.
- Discussing ideas on future development of the API.
- Sharing the applications and websites you built that use the API.
