Skip to content

E
edx-analytics-data-api
Commit 4303e086 by Mark Hoeber
Options

Alpha Data Analytics API Doc

parent bf4f5ba3
Showing with 1153 additions and 90 deletions
analytics_data_api/v0/views/courses.py
...@@ -68,30 +68,48 @@ class BaseCourseView(generics.ListAPIView): ...@@ -68,30 +68,48 @@ class BaseCourseView(generics.ListAPIView):
# pylint: disable=line-too-long # pylint: disable=line-too-long
class CourseActivityWeeklyView(BaseCourseView): class CourseActivityWeeklyView(BaseCourseView):
""" """
Weekly course activity Get counts of users who performed specific activities in a course.
Returns the course activity. Each row/item will contain all activity types for the course-week. **Example request**
<strong>Activity Types</strong> GET /api/v0/courses/{course_id}/activity/
<dl>
<dt>ANY</dt>
<dd>The number of unique users who performed any action within the course, including actions not enumerated below.</dd>
<dt>ATTEMPTED_PROBLEM</dt>
<dd>The number of unique users who answered any loncapa based question in the course.</dd>
<dt>PLAYED_VIDEO</dt>
<dd>The number of unique users who started watching any video in the course.</dd>
<dt>POSTED_FORUM</dt>
<dd>The number of unique users who created a new post, responded to a post, or submitted a comment on any forum in the course.</dd>
</dl>
If no start or end dates are passed, the data for the latest date is returned. All dates are in the UTC zone. **Response Values**
Data is sorted chronologically (earliest to latest). Returns a list of key/value pairs for student activities, as well as the
interval start and end dates and the course ID.
Date format: YYYY-mm-dd (e.g. 2014-01-31) * any: The number of unique users who performed any action in the
course, including actions not counted in other categories in the
response.
* attempted_problem: The number of unique users who answered any
loncapa-based problem in the course.
* played_video: The number of unique users who started watching any
video in the course.
* posted_forum: The number of unique users who created a new post,
responded to a post, or submitted a comment on any discussion in
the course.
* interval_start: The time and date at which data started being
included in returned values.
* interval_end: The time and date at which data stopped being
included in returned values.
* course_id: The ID of the course for which data is returned.
* created: The date the counts were computed.
start_date -- Date after which all data should be returned (inclusive) **Parameters**
end_date -- Date before which all data should be returned (exclusive)
You can specify the start and end dates for the time period for which
you want to get activity.
You specify dates in the format: YYYY-mm-ddTtttttt; for example,
``2014-12-15T000000``.
If no start or end dates are specified, the data for the week ending on
the previous day is returned.
start_date -- Date after which all data is returned (inclusive).
end_date -- Date before which all data is returned (exclusive).
""" """
slug = u'engagement-activity' slug = u'engagement-activity'
...@@ -158,29 +176,42 @@ class CourseActivityWeeklyView(BaseCourseView): ...@@ -158,29 +176,42 @@ class CourseActivityWeeklyView(BaseCourseView):
class CourseActivityMostRecentWeekView(generics.RetrieveAPIView): class CourseActivityMostRecentWeekView(generics.RetrieveAPIView):
""" """
Counts of users who performed various actions at least once during the most recently computed week. Get counts of users who performed specific activities at least once during the most recently computed week.
The default is all users who performed <strong>any</strong> action in the course. **Example request**
The representation has the following fields: GET /api/v0/courses/{course_id}/recent_activity/
<ul> **Response Values**
<li>course_id: The string identifying the course whose activity is described (e.g. edX/DemoX/Demo_Course).</li>
- interval_start: All data from this timestamp up to the `interval_end` was considered when computing this data Returns a list of key/value pairs for student activities, as well as the
point. interval start and end dates and the course ID.
- interval_end: All data from `interval_start` up to this timestamp was considered when computing this data point.
Note that data produced at exactly this time is **not** included. * activity_type: The type of activity counted. Possible values are:
- activity_type: The type of activity requested. Possible values are:
- ANY: The number of unique users who performed any action within the course, including actions not * any: The number of unique users who performed any action in the
enumerated below. course, including actions not counted in other categories in the
- PLAYED_VIDEO: The number of unique users who started watching any video in the course. response.
- ATTEMPTED_PROBLEM: The number of unique users who answered any loncapa based question in the course. * attempted_problem: The number of unique users who answered any
- POSTED_FORUM: The number of unique users who created a new post, responded to a post, or submitted a comment loncapa-based problem in the course.
on any forum in the course. * played_video: The number of unique users who started watching
- count: The number of users who performed the activity indicated by the `activity_type`. any video in the course.
</ul> * posted_forum: The number of unique users who created a new post,
responded to a post, or submitted a comment on any discussion in
activity_type -- The type of activity. (Defaults to "any".) the course.
* count: The number of unique users who performed the specified
action.
* interval_start: The time and date at which data started being
included in returned values.
* interval_end: The time and date at which data stopped being
included in returned values.
* course_id: The ID of the course for which data is returned.
**Parameters**
You can specify the activity type for which you want to get the count.
activity_type -- The type of activity: any (default), attempted_problem, played_video, posted_forum.
""" """
...@@ -245,18 +276,37 @@ class BaseCourseEnrollmentView(BaseCourseView): ...@@ -245,18 +276,37 @@ class BaseCourseEnrollmentView(BaseCourseView):
class CourseEnrollmentByBirthYearView(BaseCourseEnrollmentView): class CourseEnrollmentByBirthYearView(BaseCourseEnrollmentView):
""" """
Course enrollment broken down by user birth year Get the number of enrolled users by birth year.
Returns the enrollment of a course with users binned by their birth years. **Example request**
If no start or end dates are passed, the data for the latest date is returned. All dates are in the UTC zone. GET /api/v0/courses/{course_id}/enrollment/birth_year/
Data is sorted chronologically (earliest to latest). **Response Values**
Date format: YYYY-mm-dd (e.g. 2014-01-31) Returns an array with a collection for each year in which a user was
born. Each collection contains:
start_date -- Date after which all data should be returned (inclusive) * course_id: The ID of the course for which data is returned.
end_date -- Date before which all data should be returned (exclusive) * date: The date for which the enrollment count was computed.
* birth_year: The birth year for which the enrollment count applies.
* count: The number of users who were born in the specified year.
* created: The date the count was computed.
**Parameters**
You can specify the start and end dates for which to count enrolled
users.
You specify dates in the format: YYYY-mm-dd; for example,
``2014-12-15``.
If no start or end dates are specified, the data for the previous day is
returned.
start_date -- Date after which enrolled students are counted (inclusive).
end_date -- Date before which enrolled students are counted (exclusive).
""" """
slug = u'enrollment-age' slug = u'enrollment-age'
...@@ -266,18 +316,39 @@ class CourseEnrollmentByBirthYearView(BaseCourseEnrollmentView): ...@@ -266,18 +316,39 @@ class CourseEnrollmentByBirthYearView(BaseCourseEnrollmentView):
class CourseEnrollmentByEducationView(BaseCourseEnrollmentView): class CourseEnrollmentByEducationView(BaseCourseEnrollmentView):
""" """
Course enrollment broken down by user level of education Get the number of enrolled users by education level.
**Example request**
Returns the enrollment of a course with users binned by their education levels. GET /api/v0/courses/{course_id}/enrollment/education/
If no start or end dates are passed, the data for the latest date is returned. All dates are in the UTC zone. **Response Values**
Data is sorted chronologically (earliest to latest). Returns a collection for each level of education reported by a user.
Each collection contains:
Date format: YYYY-mm-dd (e.g. 2014-01-31) * course_id: The ID of the course for which data is returned.
* date: The date for which the enrollment count was computed.
* education_level: The education level for which the enrollment
count applies.
* count: The number of userswho reported the specified education
level.
* created: The date the count was computed.
start_date -- Date after which all data should be returned (inclusive) **Parameters**
end_date -- Date before which all data should be returned (exclusive)
You can specify the start and end dates for which to count enrolled
users.
You specify dates in the format: YYYY-mm-dd; for
example, ``2014-12-15``.
If no start or end dates are specified, the data for the previous day is
returned.
start_date -- Date after which enrolled students are counted (inclusive).
end_date -- Date before which enrolled students are counted (exclusive).
""" """
slug = u'enrollment-education' slug = u'enrollment-education'
serializer_class = serializers.CourseEnrollmentByEducationSerializer serializer_class = serializers.CourseEnrollmentByEducationSerializer
...@@ -286,18 +357,38 @@ class CourseEnrollmentByEducationView(BaseCourseEnrollmentView): ...@@ -286,18 +357,38 @@ class CourseEnrollmentByEducationView(BaseCourseEnrollmentView):
class CourseEnrollmentByGenderView(BaseCourseEnrollmentView): class CourseEnrollmentByGenderView(BaseCourseEnrollmentView):
""" """
Course enrollment broken down by user gender Get the number of enrolled users by gender.
**Example request**
GET /api/v0/courses/{course_id}/enrollment/gender/
Returns the enrollment of a course where each row/item contains user genders for the day. **Response Values**
If no start or end dates are passed, the data for the latest date is returned. All dates are in the UTC zone. Returns the count of each gender specified by users:
Data is sorted chronologically (earliest to latest). * course_id: The ID of the course for which data is returned.
* date: The date for which the enrollment count was computed.
* female: The count of self-identified female users.
* male: The count of self-identified male users.
* other: The count of self-identified other users.
* unknown: The count of users who did not specify a gender.
* created: The date the counts were computed.
Date format: YYYY-mm-dd (e.g. 2014-01-31) **Parameters**
start_date -- Date after which all data should be returned (inclusive) You can specify the start and end dates for which to count enrolled
end_date -- Date before which all data should be returned (exclusive) users.
You specify dates in the format: YYYY-mm-dd; for
example, ``2014-12-15``.
If no start or end dates are specified, the data for the previous day is
returned.
start_date -- Date after which enrolled students are counted (inclusive).
end_date -- Date before which enrolled students are counted (exclusive).
""" """
slug = u'enrollment-gender' slug = u'enrollment-gender'
serializer_class = serializers.CourseEnrollmentByGenderSerializer serializer_class = serializers.CourseEnrollmentByGenderSerializer
...@@ -329,16 +420,35 @@ class CourseEnrollmentByGenderView(BaseCourseEnrollmentView): ...@@ -329,16 +420,35 @@ class CourseEnrollmentByGenderView(BaseCourseEnrollmentView):
class CourseEnrollmentView(BaseCourseEnrollmentView): class CourseEnrollmentView(BaseCourseEnrollmentView):
""" """
Returns the enrollment count for the specified course. Get the number of enrolled users.
**Example request**
GET /api/v0/courses/{course_id}/enrollment/
**Response Values**
If no start or end dates are passed, the data for the latest date is returned. All dates are in the UTC zone. Returns the count of enrolled users:
Data is sorted chronologically (earliest to latest). * course_id: The ID of the course for which data is returned.
* date: The date for which the enrollment count was computed.
* count: The count of enrolled users.
* created: The date the count was computed.
Date format: YYYY-mm-dd (e.g. 2014-01-31) **Parameters**
start_date -- Date after which all data should be returned (inclusive) You can specify the start and end dates for which to count enrolled
end_date -- Date before which all data should be returned (exclusive) users.
You specify dates in the format: YYYY-mm-dd; for
example, ``2014-12-15``.
If no start or end dates are specified, the data for the previous day is
returned.
start_date -- Date after which enrolled students are counted (inclusive).
end_date -- Date before which enrolled students are counted (exclusive).
""" """
slug = u'enrollment' slug = u'enrollment'
serializer_class = serializers.CourseEnrollmentDailySerializer serializer_class = serializers.CourseEnrollmentDailySerializer
...@@ -347,16 +457,38 @@ class CourseEnrollmentView(BaseCourseEnrollmentView): ...@@ -347,16 +457,38 @@ class CourseEnrollmentView(BaseCourseEnrollmentView):
class CourseEnrollmentModeView(BaseCourseEnrollmentView): class CourseEnrollmentModeView(BaseCourseEnrollmentView):
""" """
Course enrollment broken down by enrollment mode. Get the number of enrolled users by enrollment mode.
**Example request**
GET /api/v0/courses/{course_id}/enrollment/mode/
**Response Values**
If no start or end dates are passed, the data for the latest date is returned. All dates are in the UTC zone. Returns the counts of users by mode:
Data is sorted chronologically (earliest to latest). * course_id: The ID of the course for which data is returned.
* date: The date for which the enrollment count was computed.
* count: The total count of enrolled users.
* created: The date the counts were computed.
* honor: The number of users enrolled in honor code mode.
* professional: The number of users enrolled in professional mode.
* verified: The number of users enrolled in verified mode.
Date format: YYYY-mm-dd (e.g. 2014-01-31) **Parameters**
start_date -- Date after which all data should be returned (inclusive) You can specify the start and end dates for which to count enrolled
end_date -- Date before which all data should be returned (exclusive) users.
You specify dates in the format: YYYY-mm-dd; for
example, ``2014-12-15``.
If no start or end dates are specified, the data for the previous day is
returned.
start_date -- Date after which enrolled students are counted (inclusive).
end_date -- Date before which enrolled students are counted (exclusive).
""" """
slug = u'enrollment_mode' slug = u'enrollment_mode'
...@@ -395,23 +527,47 @@ class CourseEnrollmentModeView(BaseCourseEnrollmentView): ...@@ -395,23 +527,47 @@ class CourseEnrollmentModeView(BaseCourseEnrollmentView):
# pylint: disable=line-too-long # pylint: disable=line-too-long
class CourseEnrollmentByLocationView(BaseCourseEnrollmentView): class CourseEnrollmentByLocationView(BaseCourseEnrollmentView):
""" """
Course enrollment broken down by user location Get the number of enrolled users by location.
Location is calculated based on the user's IP address. Users whose location
cannot be determined are counted as having a country.name of UNKNOWN.
Countries are denoted by their ISO 3166 country code.
**Example request**
Returns the enrollment of a course with users binned by their location. Location is calculated based on the user's GET /api/v0/courses/{course_id}/enrollment/location/
IP address. Enrollment counts for users whose location cannot be determined will be included in an entry with
country.name set to UNKNOWN.
Countries are denoted by their <a href="http://www.iso.org/iso/country_codes/country_codes" target="_blank">ISO 3166 country code</a>. **Response Values**
If no start or end dates are passed, the data for the latest date is returned. All dates are in the UTC zone. Returns counts of genders specified by users:
Data is sorted chronologically (earliest to latest). * course_id: The ID of the course for which data is returned.
* date: The date for which the enrollment count was computed.
* country: Contains the following fields:
Date format: YYYY-mm-dd (e.g. 2014-01-31) * alpha2: The two-letter country code.
* alpha3: The three-letter country code.
* name: The country name.
* count: The count of users from the country.
* created: The date the count was computed.
start_date -- Date after which all data should be returned (inclusive) **Parameters**
end_date -- Date before which all data should be returned (exclusive)
You can specify the start and end dates for which to count enrolled
users.
You specify dates in the format: YYYY-mm-dd; for
example, ``2014-12-15``.
If no start or end dates are specified, the data for the previous day is
returned.
start_date -- Date after which enrolled students are counted (inclusive).
end_date -- Date before which enrolled students are counted (exclusive).
""" """
slug = u'enrollment-location' slug = u'enrollment-location'
serializer_class = serializers.CourseEnrollmentByCountrySerializer serializer_class = serializers.CourseEnrollmentByCountrySerializer
model = models.CourseEnrollmentByCountry model = models.CourseEnrollmentByCountry
......
analytics_data_api/v0/views/problems.py
...@@ -12,9 +12,34 @@ from analytics_data_api.v0.serializers import SequentialOpenDistributionSerializ ...@@ -12,9 +12,34 @@ from analytics_data_api.v0.serializers import SequentialOpenDistributionSerializ
class ProblemResponseAnswerDistributionView(generics.ListAPIView): class ProblemResponseAnswerDistributionView(generics.ListAPIView):
""" """
Distribution of student answers for a particular problem, as used in a particular course. Get the distribution of student answers to a specific problem.
Results are available for most (but not all) multiple-choice and short answer response types. **Example request**
GET /api/v0/problems/{problem_id}/answer_distribution
**Response Values**
Returns a collection for each unique answer given to specified
problem. Each collection contains:
* course_id: The ID of the course for which data is returned.
* module_id: The ID of the problem.
* part_id: The ID for the part of the problem. For multi-part
problems, a collection is returned for each part.
* correct: Whether the answer was correct (``true``) or not
(``false``).
* count: The number of times the answer in this collection was
given.
* value_id: The ID of the answer in this collection.
* answer_value_text: The text of this answer, for text problems.
* answer_value_numeric: The number for this answer, for numeric
problems.
* problem_display_name: The display name for the specified problem.
* question_text: The question for the specified problem.
* variant: For randomized problems, the random seed used. If problem
is not randomized, value is null.
* created: The date the count was computed.
""" """
serializer_class = ProblemResponseAnswerDistributionSerializer serializer_class = ProblemResponseAnswerDistributionSerializer
...@@ -28,7 +53,24 @@ class ProblemResponseAnswerDistributionView(generics.ListAPIView): ...@@ -28,7 +53,24 @@ class ProblemResponseAnswerDistributionView(generics.ListAPIView):
class GradeDistributionView(generics.ListAPIView): class GradeDistributionView(generics.ListAPIView):
""" """
Distribution of grades for a particular module in a given course Get the distribution of grades for a specific problem.
**Example request**
GET /api/v0/problems/{problem_id}/grade_distribution
**Response Values**
Returns a collection for each unique grade given to a specified
problem. Each collection contains:
* course_id: The ID of the course for which data is returned.
* module_id: The ID of the problem.
* grade: The grade being counted in this collection.
* count: The number of times the grade in this collection was
given.
* max_grade: The highest possible grade for this problem.
* created: The date the count was computed.
""" """
serializer_class = GradeDistributionSerializer serializer_class = GradeDistributionSerializer
...@@ -42,7 +84,21 @@ class GradeDistributionView(generics.ListAPIView): ...@@ -42,7 +84,21 @@ class GradeDistributionView(generics.ListAPIView):
class SequentialOpenDistributionView(generics.ListAPIView): class SequentialOpenDistributionView(generics.ListAPIView):
""" """
Distribution of view counts for a particular module in a given course Get the number of views of a subsection, or sequential, in the course.
**Example request**
GET /api/v0/problems/{module_id}/sequential_open_distribution
**Response Values**
Returns a collection that contains the number of views of the specified
problem. The collection contains:
* course_id: The ID of the course for which data is returned.
* module_id: The ID of the subsection, or sequential.
* count: The number of times the subsection was viewed.
* created: The date the count computed.
""" """
serializer_class = SequentialOpenDistributionSerializer serializer_class = SequentialOpenDistributionSerializer
......
docs/api/Makefile 0 → 100644
# Makefile for Sphinx documentation
#
# You can set these variables from the command line.
SPHINXOPTS ?=
SPHINXBUILD ?= sphinx-build
PAPER ?=
BUILDDIR ?= build
# User-friendly check for sphinx-build
ifeq ($(shell which $(SPHINXBUILD) >/dev/null 2>&1; echo $$?), 1)
$(error The '$(SPHINXBUILD)' command was not found. Make sure you have Sphinx installed, then set the SPHINXBUILD environment variable to point to the full path of the '$(SPHINXBUILD)' executable. Alternatively you can add the directory with the executable to your PATH. If you don't have Sphinx installed, grab it from http://sphinx-doc.org/)
endif
Q_FLAG =
ifeq ($(quiet), true)
Q_FLAG = -Q
endif
# Internal variables.
PAPEROPT_a4 = -D latex_paper_size=a4
PAPEROPT_letter = -D latex_paper_size=letter
ALLSPHINXOPTS = $(Q_FLAG) -d $(BUILDDIR)/doctrees -c source $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source
# the i18n builder cannot share the environment and doctrees with the others
I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source
.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest gettext
help:
@echo "Please use \`make <target>' where <target> is one of"
@echo " html to make standalone HTML files"
@echo " dirhtml to make HTML files named index.html in directories"
@echo " singlehtml to make a single large HTML file"
@echo " pickle to make pickle files"
@echo " json to make JSON files"
@echo " htmlhelp to make HTML files and a HTML help project"
@echo " qthelp to make HTML files and a qthelp project"
@echo " devhelp to make HTML files and a Devhelp project"
@echo " epub to make an epub"
@echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
@echo " latexpdf to make LaTeX files and run them through pdflatex"
@echo " text to make text files"
@echo " man to make manual pages"
@echo " texinfo to make Texinfo files"
@echo " info to make Texinfo files and run them through makeinfo"
@echo " gettext to make PO message catalogs"
@echo " changes to make an overview of all changed/added/deprecated items"
@echo " linkcheck to check all external links for integrity"
@echo " doctest to run all doctests embedded in the documentation (if enabled)"
clean:
-rm -rf $(BUILDDIR)/*
html:
$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
@echo
@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
dirhtml:
$(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
@echo
@echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
singlehtml:
$(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml
@echo
@echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml."
pickle:
$(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle
@echo
@echo "Build finished; now you can process the pickle files."
json:
$(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json
@echo
@echo "Build finished; now you can process the JSON files."
htmlhelp:
$(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp
@echo
@echo "Build finished; now you can run HTML Help Workshop with the" \
".hhp project file in $(BUILDDIR)/htmlhelp."
qthelp:
$(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp
@echo
@echo "Build finished; now you can run "qcollectiongenerator" with the" \
".qhcp project file in $(BUILDDIR)/qthelp, like this:"
@echo "# qcollectiongenerator $(BUILDDIR)/qthelp/edX.qhcp"
@echo "To view the help file:"
@echo "# assistant -collectionFile $(BUILDDIR)/qthelp/edX.qhc"
devhelp:
$(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp
@echo
@echo "Build finished."
@echo "To view the help file:"
@echo "# mkdir -p $$HOME/.local/share/devhelp/edX"
@echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/edX"
@echo "# devhelp"
epub:
$(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub
@echo
@echo "Build finished. The epub file is in $(BUILDDIR)/epub."
latex:
$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
@echo
@echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex."
@echo "Run \`make' in that directory to run these through (pdf)latex" \
"(use \`make latexpdf' here to do that automatically)."
latexpdf:
$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
@echo "Running LaTeX files through pdflatex..."
$(MAKE) -C $(BUILDDIR)/latex all-pdf
@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
text:
$(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text
@echo
@echo "Build finished. The text files are in $(BUILDDIR)/text."
man:
$(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man
@echo
@echo "Build finished. The manual pages are in $(BUILDDIR)/man."
texinfo:
$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
@echo
@echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo."
@echo "Run \`make' in that directory to run these through makeinfo" \
"(use \`make info' here to do that automatically)."
info:
$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
@echo "Running Texinfo files through makeinfo..."
make -C $(BUILDDIR)/texinfo info
@echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo."
gettext:
$(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale
@echo
@echo "Build finished. The message catalogs are in $(BUILDDIR)/locale."
changes:
$(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes
@echo
@echo "The overview file is in $(BUILDDIR)/changes."
linkcheck:
$(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck
@echo
@echo "Link check complete; look for any errors in the above output " \
"or in $(BUILDDIR)/linkcheck/output.txt."
doctest:
$(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest
@echo "Testing of doctests in the sources finished, look at the " \
"results in $(BUILDDIR)/doctest/output.txt."
docs/api/requirements.txt 0 → 100644
-r ../../requirements.txt
docs/api/source/authentication.rst 0 → 100644
.. _edX Data Analytics API Authentication:
######################################
edX Data Analytics API Authentication
######################################
The edX Data Analytics API uses the Django REST framework
`TokenAuthentication`_.
**************************
Create a User and Token
**************************
You create users and tokens in the Data Analytics API server. In the server
terminal, enter:
``$ ./manage.py set_api_key <username> <token>``
.. include:: links.rst
\ No newline at end of file
docs/api/source/conf.py 0 → 100644
import sys
import os
from path import path
on_rtd = os.environ.get('READTHEDOCS', None) == 'True'
# sys.path.insert(0, os.path.abspath('..'))
# Add any paths that contain templates here, relative to this directory.
# templates_path.append('source/_templates')
# Add any paths that contain custom static files (such as style sheets) here,
# relative to this directory. They are copied after the builtin static files,
# so a file named "default.css" will overwrite the builtin "default.css".
# html_static_path.append('source/_static')
if not on_rtd: # only import and set the theme if we're building docs locally
import sphinx_rtd_theme
html_theme = 'sphinx_rtd_theme'
html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
master_doc = 'index'
# If extensions (or modules to document with autodoc) are in another directory,
# add these directories to sys.path here. If the directory is relative to the
# documentation root, use os.path.abspath to make it absolute, like shown here.
root = path('../../..').abspath()
sys.path.insert(0, root)
sys.path.append(root / "analytics_data_api/v0/views")
sys.path.append('.')
# -- General configuration -----------------------------------------------------
# django configuration - careful here
if on_rtd:
os.environ['DJANGO_SETTINGS_MODULE'] = 'analyticsdataserver.settings.local'
else:
os.environ['DJANGO_SETTINGS_MODULE'] = 'analyticsdataserver.settings.local'
# Add any Sphinx extension module names here, as strings. They can be extensions
# coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
extensions = [
'sphinx.ext.autodoc', 'sphinx.ext.doctest', 'sphinx.ext.intersphinx',
'sphinx.ext.todo', 'sphinx.ext.coverage', 'sphinx.ext.pngmath',
'sphinx.ext.mathjax', 'sphinx.ext.viewcode']
# List of patterns, relative to source directory, that match files and
# directories to ignore when looking for source files.
exclude_patterns = ['build']
project = u'edX Data Analytics API Version 0 Alpha'
copyright = u'2014, edX'
docs/api/source/courses.rst 0 → 100644
##################################################
Course Information API Module
##################################################
This page contains information to:
* `Get Weekly Course Activity`_
* `Get Recent Course Activity`_
* `Get the Course Enrollment`_
* `Get the Course Enrollment by Mode`_
* `Get the Course Enrollment by Birth Year`_
* `Get the Course Enrollment by Education Level`_
* `Get the Course Enrollment by Gender`_
* `Get the Course Enrollment by Location`_
.. _Get Weekly Course Activity:
***************************
Get Weekly Course Activity
***************************
.. autoclass:: analytics_data_api.v0.views.courses.CourseActivityWeeklyView
**Example response**
.. code-block:: json
HTTP 200 OK
Vary: Accept
Content-Type: text/html; charset=utf-8
Allow: GET, HEAD, OPTIONS
[
{
"interval_start": "2014-12-08T000000",
"interval_end": "2014-12-15T000000",
"course_id": "edX/DemoX/Demo_Course",
"any": 3013,
"attempted_problem": 206,
"played_video": 1049,
"created": "2014-12-10T193104"
}
]
.. _Get Recent Course Activity:
***************************
Get Recent Course Activity
***************************
.. autoclass:: analytics_data_api.v0.views.courses.CourseActivityMostRecentWeekView
**Example response**
.. code-block:: json
HTTP 200 OK
Vary: Accept
Content-Type: text/html; charset=utf-8
Allow: GET, HEAD, OPTIONS
{
"interval_start": "2014-12-08T00:00:00Z",
"interval_end": "2014-12-15T00:00:00Z",
"activity_type": "any",
"count": 3013,
"course_id": "edX/DemoX/Demo_Course"
}
.. _Get the Course Enrollment:
***************************
Get the Course Enrollment
***************************
.. autoclass:: analytics_data_api.v0.views.courses.CourseEnrollmentView
**Example response**
.. code-block:: json
HTTP 200 OK
Vary: Accept
Content-Type: text/html; charset=utf-8
Allow: GET, HEAD, OPTIONS
[
{
"course_id": "edX/DemoX/Demo_Course",
"date": "2014-12-10",
"count": 1892,
"created": "2014-12-10T193146"
}
]
.. _Get the Course Enrollment by Mode:
*********************************
Get the Course Enrollment by Mode
*********************************
.. autoclass:: analytics_data_api.v0.views.courses.CourseEnrollmentModeView
**Example response**
.. code-block:: json
HTTP 200 OK
Vary: Accept
Content-Type: text/html; charset=utf-8
Allow: GET, HEAD, OPTIONS
[
{
"course_id": "edX/DemoX/Demo_Course",
"date": "2014-12-10",
"count": 1890,
"created": "2014-12-10T193146",
"honor": 945,
"professional": 189,
"verified": 756
}
]
.. _Get the Course Enrollment by Birth Year:
****************************************
Get the Course Enrollment by Birth Year
****************************************
.. autoclass:: analytics_data_api.v0.views.courses.CourseEnrollmentByBirthYearView
**Example response**
.. code-block:: json
HTTP 200 OK
Vary: Accept
Content-Type: text/html; charset=utf-8
Allow: GET, HEAD, OPTIONS
[
{
"course_id": "edX/DemoX/Demo_Course",
"date": "2014-12-10",
"birth_year": 1960,
"count": 11,
"created": "2014-12-10T193146"
},
{
"course_id": "edX/DemoX/Demo_Course",
"date": "2014-12-10",
"birth_year": 1961,
"count": 58,
"created": "2014-12-10T193146"
}
]
.. _Get the Course Enrollment by Education Level:
************************************************
Get the Course Enrollment by Education Level
************************************************
.. autoclass:: analytics_data_api.v0.views.courses.CourseEnrollmentByEducationView
**Example response**
.. code-block:: json
HTTP 200 OK
Vary: Accept
Content-Type: text/html; charset=utf-8
Allow: GET, HEAD, OPTIONS
[
{
"course_id": "edX/DemoX/Demo_Course",
"date": "2014-12-10",
"education_level": "bachelors",
"count": 634,
"created": "2014-12-10T193146"
},
{
"course_id": "edX/DemoX/Demo_Course",
"date": "2014-12-10",
"education_level": "doctorate",
"count": 88,
"created": "2014-12-10T193146"
}
]
.. _Get the Course Enrollment by Gender:
************************************************
Get the Course Enrollment by Gender
************************************************
.. autoclass:: analytics_data_api.v0.views.courses.CourseEnrollmentByGenderView
**Example response**
.. code-block:: json
HTTP 200 OK
Vary: Accept
Content-Type: text/html; charset=utf-8
Allow: GET, HEAD, OPTIONS
[
{
"course_id": "edX/DemoX/Demo_Course",
"date": "2014-12-10",
"female": 732,
"male": 1155,
"other": 435,
"unknown": 0,
"created": "2014-12-10T193146"
}
]
.. _Get the Course Enrollment by Location:
************************************************
Get the Course Enrollment by Location
************************************************
.. autoclass:: analytics_data_api.v0.views.courses.CourseEnrollmentByLocationView
See `ISO 3166 country codes`_ for more information.
**Example response**
.. code-block:: json
HTTP 200 OK
Vary: Accept
Content-Type: text/html; charset=utf-8
Allow: GET, HEAD, OPTIONS
[
{
"date": "2014-12-10",
"course_id": "edX/DemoX/Demo_Course",
"country": {
"alpha2": "CA",
"alpha3": "CAN",
"name": "Canada"
},
"count": 264,
"created": "2014-12-10T193146"
},
{
"date": "2014-12-10",
"course_id": "edX/DemoX/Demo_Course",
"country": {
"alpha2": "CN",
"alpha3": "CHN",
"name": "China"
},
"count": 416,
"created": "2014-12-10T193146"
}
]
.. include:: links.rst
docs/api/source/endpoints.rst 0 → 100644
.. _Data Analytics API:
################################################
edX Data Analytics API Endpoints
################################################
The edX Platform API allows you to view information about users and their course enrollments, course information, and videos and transcripts.
The following tasks and endpoints are currently supported.
.. list-table::
:widths: 10 70
:header-rows: 1
* - To:
- Use this endpoint:
* - :ref:`Get Weekly Course Activity`
- /api/v0/courses/{course_id}/activity/
* - :ref:`Get Recent Course Activity`
- /api/v0/courses/{course_id}/recent_activity/
* - :ref:`Get the Course Enrollment`
- /api/v0/courses/{course_id}/enrollment/
* - :ref:`Get the Course Enrollment by Mode`
- /api/v0/courses/{course_id}/enrollment/mode/
* - :ref:`Get the Course Enrollment by Birth Year`
- /api/v0/courses/{course_id}/enrollment/birth_year/
* - :ref:`Get the Course Enrollment by Education Level`
- /api/v0/courses/{course_id}/enrollment/education/
* - :ref:`Get the Course Enrollment by Gender`
- /api/v0/courses/{course_id}/enrollment/gender/
* - :ref:`Get the Course Enrollment by Location`
- /api/v0/courses/{course_id}/enrollment/location/
* - :ref:`Get the Grade Distribution for a Course`
- /api/v0/problems/{problem_id}/grade_distribution
* - :ref:`Get the Answer Distribution for a Problem`
- /api/v0/problems/{problem_id}/answer_distribution
* - :ref:`Get the View Count for a Subsection`
- /api/v0/problems/{module_id}/sequential_open_distribution
\ No newline at end of file
docs/api/source/index.rst 0 → 100644
################################################
edX Data Analytics API Version 0
################################################
.. toctree::
:maxdepth: 2
read_me
overview
setup
authentication
endpoints
courses
problems
\ No newline at end of file
docs/api/source/links.rst 0 → 100644
.. _TokenAuthentication: http://www.django-rest-framework.org/api-guide/authentication/#tokenauthentication
.. _Data Analytics API repository: https://github.com/edx/edx-analytics-data-api
.. _ISO 3166 country codes: http://www.iso.org/iso/country_codes/country_codes
\ No newline at end of file
docs/api/source/overview.rst 0 → 100644
.. _edX Data Analytics API Overview:
################################################
edX Data Analytics API Overview
################################################
The edX Data Analytics API provides the tools for building applications to view
and analyze student activity in your course.
The edX Data Analytics API uses Representational State Transfer (REST) design
principles and supports JavaScript Object Notation (JSON) data-interchange
format. Our REST API is simple, lightweight and optimized.
You can use the edX Data Analytics API for web, desktop, and mobile
applications.
****************************************
edX Data Analytics API Version 0, Alpha
****************************************
The edX Data Analytics API is currently at version 0 and is an Alpha release.
We plan on making significant enhancements and changes to the API.
The Data Analytics API uses key-based authentication and currently has no
built-in authorization mechanism. Therefore third parties cannot currently use
the Data Analytics API with edx.org data.
Open edX users can use the Data Analytics API with their own instances.
EdX plans to make the Data Analytics API available to partners in the future,
and invites feedback.
***********************************
edX Data Analytics API Capabilities
***********************************
With the edX Data Analytics API, you can:
* :ref:`Get Weekly Course Activity`
* :ref:`Get Recent Course Activity`
* :ref:`Get the Course Enrollment`
* :ref:`Get the Course Enrollment by Mode`
* :ref:`Get the Course Enrollment by Birth Year`
* :ref:`Get the Course Enrollment by Education Level`
* :ref:`Get the Course Enrollment by Gender`
* :ref:`Get the Course Enrollment by Location`
* :ref:`Get the Grade Distribution for a Course`
* :ref:`Get the Answer Distribution for a Problem`
* :ref:`Get the View Count for a Subsection`
\ No newline at end of file
docs/api/source/problems.rst 0 → 100644
##################################################
Problem Information API Module
##################################################
This page contains information to:
* `Get the Grade Distribution for a Course`_
* `Get the Answer Distribution for a Problem`_
* `Get the View Count for a Subsection`_
.. _Get the Grade Distribution for a Course:
***************************************
Get the Grade Distribution for a Course
***************************************
.. autoclass:: analytics_data_api.v0.views.problems.GradeDistributionView
**Example response**
.. code-block:: json
HTTP 200 OK
Vary: Accept
Content-Type: text/html; charset=utf-8
Allow: GET, HEAD, OPTIONS
[
{
"module_id": "i4x://edX/DemoX/Demo_Course/problem/97fd93e33a18495488578e9e74fa4cae",
"course_id": "edX/DemoX/Demo_Course",
"grade": 1,
"max_grade": 2,
"count": 5,
"created": "2014-09-12T114957"
},
{
"module_id": "i4x://edX/DemoX/Demo_Course/problem/97fd93e33a18495488578e9e74fa4cae",
"course_id": "edX/DemoX/Demo_Course",
"grade": 2,
"max_grade": 2,
"count": 256,
"created": "2014-09-12T114957"
}
]
.. _Get the Answer Distribution for a Problem:
*******************************************
Get the Answer Distribution for a Problem
*******************************************
.. autoclass:: analytics_data_api.v0.views.problems.ProblemResponseAnswerDistributionView
**Example response**
.. code-block:: json
HTTP 200 OK
Vary: Accept
Content-Type: text/html; charset=utf-8
Allow: GET, HEAD, OPTIONS
[
{
"course_id": "edX/DemoX/Demo_Course",
"module_id": "i4x://edX/DemoX/Demo_Course/problem/
268b43628e6d45f79c52453a590f9829",
"part_id": "i4x-edX-DemoX-Demo_Course-problem-
268b43628e6d45f79c52453a590f9829_2_1",
"correct": false,
"count": 9,
"value_id": "choice_0",
"answer_value_text": "Russia",
"answer_value_numeric": null,
"problem_display_name": "Multiple Choice Problem",
"question_text": "Which of the following countries has the largest
population?",
"variant": null,
"created": "2014-12-05T225026"
},
{
"course_id": "edX/DemoX/Demo_Course",
"module_id": "i4x://edX/DemoX/Demo_Course/problem/
268b43628e6d45f79c52453a590f9829",
"part_id": "i4x-edX-DemoX-Demo_Course-problem-
268b43628e6d45f79c52453a590f9829_2_1",
"correct": true,
"count": 15,
"value_id": "choice_1",
"answer_value_text": "Indonesia",
"answer_value_numeric": null,
"problem_display_name": "Multiple Choice Problem",
"question_text": "Which of the following countries has the largest
population?",
"variant": null,
"created": "2014-12-05T225026"
}
]
.. _Get the View Count for a Subsection:
*************************************
Get the View Count for a Subsection
*************************************
.. autoclass:: analytics_data_api.v0.views.problems.SequentialOpenDistributionView
**Example response**
.. code-block:: json
HTTP 200 OK
Vary: Accept
Content-Type: text/html; charset=utf-8
Allow: GET, HEAD, OPTIONS
[
{
"module_id": "i4x://edX/DemoX/Demo_Course/sequential/5c6c207e16dd47208c29bd8d3e68861e",
"course_id": "edX/DemoX/Demo_Course",
"count": 23,
"created": "2014-09-12T114838"
}
]
\ No newline at end of file
docs/api/source/read_me.rst 0 → 100644
########
Read Me
########
The edX Data Analytics API documentation is created using RST_
files and Sphinx_. You, the user community, can help update and revise this
documentation project on GitHub:
https://github.com/edx/edx-analytics-data-api/tree/master/docs/api/source
To suggest a revision, fork the project, make changes in your fork, and submit
a pull request back to the original project: this is known as the `GitHub Flow`_.
.. _Sphinx: http://sphinx-doc.org/
.. _LaTeX: http://www.latex-project.org/
.. _`GitHub Flow`: https://github.com/blog/1557-github-flow-in-the-browser
.. _RST: http://docutils.sourceforge.net/rst.html
\ No newline at end of file
docs/api/source/setup.rst 0 → 100644
.. _Set up the Data Analytics API Server:
######################################
Set up the Data Analytics API Server
######################################
This chapter describes how to set up and test the edX Data Analytics API
server:
#. `Get the Repository`_
#. `Install Server Requirements`_
#. `Run the Server`_
#. `Load Sample Data`_
#. `Test the Data Analytics API`_
Also see :ref:`edX Data Analytics API Authentication`.
**************************
Get the Repository
**************************
You must get the `Data Analytics API repository`_ from GitHub.
From the terminal, enter:
``git clone https://github.com/edx/edx-analytics-data-api``
You may choose to get the repository in a virtual environment.
****************************
Install Server Requirements
****************************
From the terminal at the top level of the server repository, enter:
``$ make develop``
Server requirements are then installed.
****************************
Run the Server
****************************
From the terminal at the top level of the server repository, enter:
``$ ./manage.py runserver``
The server starts.
****************************
Load Sample Data
****************************
From the terminal at the top level of the server repository, enter:
``$ make loaddata``
****************************
Test the Data Analytics API
****************************
After you load sample data and run the server, you can test the API.
#. In a browser, go to: ``http://<server-name>:<port>/docs/#!/api/``
#. Enter a valid key and click **Explore**.
See :ref:`edX Data Analytics API Authentication` for information on keys.
You see an interactive list of API endpoints, which you can use to get
responses with the sample data. Expand the **api** section to see the
available endpoints.
.. image:: images/api_test.png
:alt: The API test web page
3. Expand the section for an endpoint:
.. image:: images/api_test_expand.png
:alt: The API test web page with an expanded endpoint
4. Enter parameters as needed and click **Try it out**. The response opens:
.. image:: images/api_test_response.png
:alt: The API test web page with a response
To get the sample enrollment data, use ``edX/DemoX/Demo_Course`` as the
``course_id``.
.. include:: links.rst
\ No newline at end of file
requirements/base.txt
...@@ -3,7 +3,7 @@ Markdown==2.4.1 # BSD ...@@ -3,7 +3,7 @@ Markdown==2.4.1 # BSD
django-model-utils==1.4.0 # BSD django-model-utils==1.4.0 # BSD
djangorestframework==2.4.4 # BSD djangorestframework==2.4.4 # BSD
ipython==2.1.0 # BSD ipython==2.1.0 # BSD
django-rest-swagger==0.1.14 # BSD django-rest-swagger==0.2.5 # BSD
djangorestframework-csv==1.3.3 # BSD djangorestframework-csv==1.3.3 # BSD
iso3166==0.1 # MIT iso3166==0.1 # MIT
-e git+https://github.com/edx/opaque-keys.git@d45d0bd8d64c69531be69178b9505b5d38806ce0#egg=opaque-keys -e git+https://github.com/edx/opaque-keys.git@d45d0bd8d64c69531be69178b9505b5d38806ce0#egg=opaque-keys
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment