GeoGebraTube API

The GeoGebraTube API is an easy way to incorporate GeoGebraTube into applications and websites. This page will contain documentation and examples of how to use the API as soon as it is ready for public usage.

First Example

This first example demonstrates how to request information about English materials matching the search for the term "integral". The fields url, title, author and author_url of all matching materials are returned as response. You can review the section "Fields" below for a complete list with fields available. Furthermore you can see the real-time results of this requests at ​http://www.geogebratube.org/api/test.php .

<?xml version='1.0' standalone='yes'?>
<request api='1.0.0'>
<task type='fetch'>
	<fields>
		<field name="url" />
		<field name="title" />
		<field name="author" />
		<field name="author_url" />
	</fields>
	
	<filters>
		<field name="search">integral</field>
		<field name="language">en</field>
	</filters>
	
	<order by="timestamp" type="desc" />
	<limit num="3" />
</task>
</request>

Structure of a Request

Root

The root tag of each request must be <request> with the API version number supplied in the attribute version. The version number's purpose is to keep compatibility between your program and GeoGebraTube's API. The current version of the API is 1.0.0.

<?xml version='1.0' standalone='yes'?>
<request api='1.0.0'>
	... (tasks) ...
</request>

Tasks

At the moment each request must contain exactly one task for the API to perform, all information belonging to a single task must therefore be surrounded with a <task> tag. This task must supply the task type as attribute type, at the moment just materials can be fetched and the value of the attribute must be fetch.

<task type='fetch'>
	... (detail information) ...
</task>

Tasks: Fetching

Fetching materials, ie getting data about materials stored in GeoGebraTube, is conceptually very similar to fetching data from a database. There is a list of field names, a way to characterize which materials to fetch (SQL: WHERE), the number of materials you want to fetch at maximum (MySQL: LIMIT) and the ordering of the results (SQL: ORDER BY). Just the field name list is mandatory.

Fields

The syntax is very simple: You must provide a list with the names of the fields you want to fetch, a complete list of all fields can be found below. Each field has it's own <field> tag, where the name attribute contains the field name.

<fields>
	<field name="fieldname1" />
	<field name="fieldname2" />
	<field name="fieldname3" />
	...
</fields>

Filter

The filter is like SQL's WHERE, although less powerful. Only materials which matches all criteria specified in the filter are returned. Filters can be read like "condition A must apply to field B", each tag in the filter block is for a single field and is called <field>. The field name is given as attribute name as well, the value the field must match to pass the condition is given as value inside the tag. There is also a comp attribute with two valid values, eq and like. eq is the default value and means that the values must be equal. like is similar to the SQL LIKE comparison method (ie the filter value must occur somewhere in the field value, but does not have to match it exactly).

The most important fields for filtering are id to fetch a single material by ID and search to search for materials (eg using a search field). Most of the fields for fetching can also be used for filtering.

<filters>
	<field name="title" comp="like">titlepart</field>
	<field name="search">term</field>
	<field name="language">en,fr,de</field>
</filters>

Ordering

Most fields can also be used for ordering of the result set. The order is a single field using fieldname to specify the field to order by and the type of ordering: Set the attribute type to asc for ascending and desc for descending ordering.

<order by="fieldname" type="desc" />

Limiting Material Numbers

The number of materials returned by the API is limited to 5 automatically. You can change that limit to anything between 1 and 30 by using the <limit> tag:

<limit num="3" />

Fields

Below is a list of all fields with description of their values. The second, third and forth columns are indicating in which context this field may be used.

Field Name	Fetching	Filtering	Ordering	Description
id	yes	yes	yes	ID of the material.
title	yes	yes	yes	Title of the material.
search	no	yes	no	Search for a term in titles, tags and descriptions of materials. Works like the search form on GeoGebraTube.org . This is the most robust way to search for materials and should be used instead of searching for the title or description individually.
type	yes	yes	yes	Type of the material, either ggb, ggt or link.
description	yes	yes	yes	Description of the material (for teachers).
timestamp	yes	yes	yes	UNIX timestamp of this material's creation time.
author	yes	yes	yes	Name of the author.
author_url	yes	no	no	URL to the author's profile in GeoGebraTube.
url	yes	no	no	URL to the overview page of the material.
url_direct	yes	no	no	URL to the material itself (link to student page for materials of type ggb, download link for ggt, or external link for link).
language	yes	yes	yes	Two letter language code of the material. For filtering: Separate multiple languages with a comma.
thumbnail	yes	no	yes	URL of the thumbnail picture for the material. It is empty if there is no thumbnail available for the material.
featured	yes	yes	yes	true if a material is featured, false otherwise.
likes	yes	yes	yes	Number of likes this material received. Note that ascending order gives the least popular materials first.
relevance	no	no	yes	Allows for result ordering by relevance, can be only used together with the search field. Ascending order gives the least relevant material first.