Introduction

LingQ API is a language and platform neutral RESTful protocol. It allows simple programmatic access via HTTP to specific features of LingQ.

Before starting to use API, you must receive the API key. Currently, all you have to do is open the page https://www.lingq.com/accounts/apikey/ and use the displayed key in your program.

By default, all API methods returns results in the JSON format, but you can force to output the results in any of the following output formats: json, yaml, xml and python pickle by using GET parameter called format in your requests to the API. For example, request http://www.lingq.com/api_v2/languages/?format=yaml call will return list of user’s languages in the YAML format.

It is possible to limit result sets to sane amount by using pagination. To enable pagination, add offset and limit GET parameters to the request. Both parameters must be specified, but either may be left empty, exclusively, to produce the following behaviors:

• ?offset=n&limit= -> tail of list, beginning at item n
• ?offset=&limit=n -> trailing n items of list

Python examples below use simplejson library for parsing results, but you can use any other library, for example, json library built in Python 2.6.

Methods

GEThttp://www.lingq.com/api_v2/languages/

Returns :target languages of the authenticated user.

Command-line example:

linguist@qa:~ % curl 'http://www.lingq.com/api_v2/languages/?apikey=bd894eabcd4c0'
["en", "es", "fr"]

linguist@qa:~ % curl 'http://www.lingq.com/api_v2/languages/?apikey=bd894eabcd4c0&format=xml'
<?xml version="1.0" encoding="utf-8"?>
<response><resource>en</resource><resource>es</resource><resource>fr</resource></response>

Python example:

import urllib2
import simplejson

API_KEY = 'bd894eabcd4c0'

url = 'http://www.lingq.com/api_v2/languages/?apikey=%s' % API_KEY
request = urllib2.Request(url)
response = urllib2.urlopen(request)
languages_json = response.read()
languages = simplejson.loads(languages_json)
for language in languages:
    print language

GEThttp://www.lingq.com/api_v2/language/lessons/

Param language:lessons for this language are returned Returns :list of user’s lessons

Command-line example:

linguist@qa:~ % curl 'http://www.lingq.com/api_v2/es/lessons/?apikey=bd894eabcd4c0'
[
{
"image_url": "/media/resources/contents/images/2007/11/22/apple-orange-120.jpg",
"id": 28973,
"cards_count": 1,
"title": "Cómo comprar en el mercado"
},
{
"image_url": "/media/resources/contents/images/2007/10/24/clock.jpg",
"id": 28262,
"cards_count": 1,
"title": "la hora"
}
]

linguist@qa:~ % curl 'http://www.lingq.com/api_v2/es/lessons/?apikey=bd894eabcd4c0&format=yaml'
- {cards_count: 1, id: 28973, image_url: /media/resources/contents/images/2007/11/22/apple-orange-120.jpg,
title: "C\xF3mo comprar en el mercado"}
- {cards_count: 1, id: 28262, image_url: /media/resources/contents/images/2007/10/24/clock.jpg,
title: la hora}

Python example:

url = 'http://www.lingq.com/api_v2/es/lessons/?apikey=%s' % API_KEY
response = urllib2.urlopen(url)
lessons = simplejson.loads(response.read())
for lesson in lessons:
    print 'Lesson id: %(id)d, title: "%(title)s", cards count: %(cards_count)d' % lesson

GEThttp://www.lingq.com/api_v2/language/content_id/lingqs/

Param language:Language of the LingQs Param content_id:  Return LingQs related to this lesson. If this parameter is not specified, all LingQs are returned Returns :list of all LingQs related to content with content_id. If not specified, return list of all LingQs.

Command-line example:

linguist@qa:~ % curl 'http://www.lingq.com/api_v2/es/lingqs/?apikey=bd894eabcd4c0'
[
{
"status": 2,
"fragment": "siete horas",
"term": "hora",
"id": 2782310,
"hint": "hour"
},
{
"status": 0,
"fragment": "Cada día te extraño más.",
"term": "extraño",
"id": 3950935,
"hint": "strange, odd"
}
]
linguist@qa:~ % curl 'http://www.lingq.com/api_v2/es/28972/lingqs/?apikey=bd894eabcd4c0'
[
{
"status": 2,
"fragment": "siete horas",
"term": "hora",
"id": 2782310,
"hint": "hour"
}
]

Python example:

url = 'http://www.lingq.com/api_v2/es/lingqs/?apikey=%s' % API_KEY
response = urllib2.urlopen(url)
lingqs = simplejson.loads(response.read())
print lingqs[0]['fragment'], lingqs[0]['status']

POSThttp://www.lingq.com/api_v2/language/lingqs/

Create LingQ

Param language:Language of the LingQ Param status (optional):  Status of the LingQ being created Param term:Term for which LingQ is being created Param hint (optional):  Hint for the LingQ being created Param fragment (optional):  Phrase where LingQ being created was found

Command-line example:

linguist@qa:~ % curl -X POST -d 'status=3;fragment=siete;hint=hour;term=siete%20horas' 'http://www.lingq.com/api_v2/es/lingqs/?apikey=bd894eabcd4c0'
Created

PUThttp://www.lingq.com/api_v2/language/lingqs/

Update LingQ

Param language:Language of the LingQ Param id:id of the LingQ to update Param status (optional):  New status (0-3) Param hint (optional):  New hint Param fragment (optional):  New fragment Returns :‘OK’ string if LingQ was updated successfully

Command-line example:

linguist@qa:~ % curl -X PUT -d 'id=2782310;status=3;fragment=siete;hint=hour' 'http://www.lingq.com/api_v2/es/lingqs/?apikey=bd894eabcd4c0'
OK

PUThttp://www.lingq.com/api_v2/batch-update/

Allows to modify several LingQs at once. Requires JSON list of objects with fields:

• id (required)
• hint (optional)
• fragment (optional)
• status (optional)

Command-line example:

linguist@qa:~ % curl -X PUT -d '[{"id": 4932947, "hint": "test 1"},{"id": 4932946, "fragment": "test 2"}]' 'http://192.168.1.2:8000/api_v2/batch-update/?apikey=bd894eabcd4c0'
OK

Python example:

import json
from httplib2 import Http

h = Http()
cards = [{'id': 2782310, 'status': 0, 'fragment': 'cinco horas'}, {'id': 4932946, 'status': 3}]
url = 'http://www.lingq.com/api_v2/batch-update/?apikey=%s' % API_KEY
resp, content = h.request(url, "PUT", json.dumps(cards))
print resp

GEThttp://www.lingq.com/api_v2/language/repetition-lingqs/

Returns list of LingQs of the day for the last 5 days.

Command-line example:

linguist@qa:~ % curl 'http://www.lingq.com/api_v2/en/repetition-lingqs/?apikey=bd894eabcd4c0'
{
  "2010-12-11": [{
      "id": 2782310,
      "term": "5 hours",
      "status": 0,
      "fragment": "cinco horas"
  }],
  "2010-12-10": [],
  "2010-12-13": [],
  "2010-12-12": [],
  "2010-12-14": []
}

GEThttp://www.lingq.com/api_v2/content_id/text/

Returns lesson text and related LingQs.

Command-line example:

linguist@qa:~ % curl 'http://www.lingq.com/api_v2/en/35411/text/?apikey=bd894eabcd4c0'
{
 "cards": [
     {
         "status": 0,
         "fragment": "statements only reflect",
         "term": "only",
         "id": 4932948,
         "hint": ""
     }
 ],
 "text": "Some statements only reflect opinions..."
}

PUThttp://www.lingq.com/api_v2/language/content_id/update-stats/

Allows to modify statistics of the lesson.

Param language:language of the lesson Param content_id:  id of the lesson to be updated Param read_times:  number of times lesson was read Param listen_times:  number of times lesson audio was listened to

Command-line example:

linguist@qa:~ % curl -X PUT -d 'read_times=5;listen_times=4' 'http://www.lingq.com/api_v2/es/35411/update-stats/?apikey=bd894eabcd4c0'
OK

GEThttp://www.lingq.com/api_v2/profile/

Returns user profile information.

language

code of the language the user is currently studying

level

user’s tier level (0 means free, all other levels are paid)

locale

user’s locale

time_zone

user’s time zone

native_language

user’s native language

dictionary_locale

user’s dictionary locale

points

number of points on user’s account

Command-line example:

linguist@qa:~ % curl 'http://www.lingq.com/api_v2/profile/?apikey=bd894eabcd4c0'
{
  "language": "en",
  "level": 0,
  "locale": "en",
  "time_zone": "Europe/Moscow",
  "native_language": "Russian",
  "dictionary_locale": "en",
  "points": 4500
}