Q-Translate API Reference

report

stats

General statistics (number of likes and translations) for the last week, month and year.

GET api/report/stats
lng
language of translations
POST api/report/stats
lng
language of translations

Examples: 

curl -H 'Accept: application/json' \
     'https://qtr.fs.al/api/report/stats?lng=en' | python -m json.tool
curl -H 'Content-type: application/json' \
     -X POST https://qtr.fs.al/api/report/stats \
     -d '{"lng": "sq"}' | python -m json.tool

topusers

Statistics about top contributing users.

GET api/report/topcontrib
lng
language of translations
period
period of report (last day | week | month | year)
size
number of results (top contributers), between 5 and 100
POST api/report/topcontrib
lng
language of translations
period
period of report (last day | week | month | year)
size
number of results (top contributers), between 5 and 100

Examples: 

curl -H 'Accept: application/json' \
     'https://qtr.fs.al/api/report/topusers?lng=en&period=week' \
     | python -m json.tool
curl -H 'Accept: application/json' -H 'Content-type: application/json' \
     -X POST https://qtr.fs.al/api/report/topusers \
     -d '{"lng": "en", "period": "week", "size": 10}' \
     | python -m json.tool

translations

get

Get a verse, along with its translations, likes and other details.

GET api/translations/$selector
selector
Translation selector, in the form 'lng:chapter:verse'
POST api/translations/get
lng
The language of translations, like en, fr, de, etc.
chapter
Chapter number.
verse
Verse number.

Examples: 

curl -k -H 'Accept: application/json' \
     'https://qtr.fs.al/api/translations/en:2:3' \
     | python -m json.tool
curl -k -H 'Content-type: application/json' \
     -X POST https://qtr.fs.al/api/translations/get
     -d '{"lng": "en", "chapter": "2", "verse": "3"}' \
     | python -m json.tool
curl -k -H 'Accept: application/json' \
     'https://qtranslate.fs.al/qtr/en/2/3' \
     | python -m json.tool

add

Add a new translation to a verse.

POST api/translations/add
lng
The language (code) of the new translation.
chapter
Chapter number.
verse
Verse number.
translation
The new translation as a string.

Examples:

like

Add a like for the given translation.

POST api/translations/like
tguid
ID of the translation

Examples:

del

Delete a translation

POST api/translations/del
tguid
ID of the translation

Examples:

search

Search verses and translations using various filters.

GET api/translations
This provides the same functionality and has the same parameters as the search operation. The only difference is that the parameters are provided as a GET request (in the URL), whereas the parameters of 'search' are provided as a POST request. Sometimes this may be more convenient.
POST api/translations/search
lng
The language of translations.
limit
The number of results to be returned (min: 5, max: 50).
words
Words to be searched for.
chapter
The chapter to search on.
type
Type of search:
  • similar : Search words by similarity.
  • logical : Search using logical (boolean) rules. For example the sign + (or -) in front of a word indicates that the word must be present (absent) in the result. A phrase that is enclosed in double quotes (=") is matched literally. A star (=*) appended to a word acts as a wildcard (matches all the words starting with that word).
what
What to search:
  • translations : Search translations.
  • verses : Search verses.
page
Page of results to be displayed.
only_mine
(boolean) Limit search only to the verses touched (translated or voted) by the current user.
translated_by
Limit search by the author of translations (can be used only by admins).
voted_by
Limit search by a user (can be used only by admins).
date_filter
Which date to filter (used only by admins). Can be one of:
  • translations : Filter Translations By Date (default)
  • likes : Filter Likes By Date
from_date
Date and time.
to_date
Date and time.
GET translations/search
Search strings and translations using various filters. If the request header Accept: application/json is set, then the output will be in JSON (otherwise it will be an HTML page). It gets the same parameters as GET api/translations

Examples: 

curl -k -H 'Accept: application/json' \
  'https://dev.qtr.fs.al/api/translations/search?lng=en&words=unseen&chapter=2' \
  | python -m json.tool
curl -k -H 'Accept: application/json' \
  'https://en.qtranslate.fs.al/translations/search?words=unseen&chapter=2' \
   | python -m json.tool

submit

Submit multiple actions at once.

POST api/translations/submit
Array of actions. Each action is an associated array that contains the items:
action
The action to be done: add | vote | del
params
Associative array of the needed parameters for this action.

Examples:

import

Import translations from file.

POST api/translations/import
lng
Language of translations.
author
The author of translations.
file
A text file with translations.

Returns associative array containing:

messages
Array of notification messages; each notification message is an array of a message and a type, where type can be one of status, warning, error.

For any translation in the file, it will be added as a suggestion if such a translation does not exist, or it will just be liked if such a translation already exists.

Examples:

misc

latest

GET latest/$lng[/$days[/$limit]]
Return the latest translations in JSON format. Latest means since yesterday. Results are cached, so last minute translations may not appear on the list.
lng
The language of translations.
days
Return all the translations since that many days ago. If not given, return only the translations since yesterday.
limit
Return that many translations from the latest ones, regardless of their time. This takes precedence over the number of days.

Each of the returned translations has these fields: chapter_id, verse_nr, vid, lng, translation, tguid, time, username, usermail

Examples: 

curl https://qtr.fs.al/latest/en | python -m json.tool
curl https://qtr.fs.al/latest/en/7 | python -m json.tool
curl https://qtr.fs.al/latest/en//5 | python -m json.tool

rss-feed

GET rss-feed/$lng
Return a RSS feed of the latest translations. Latest means since yesterday. Results are cached, so last minute translations may not appear on the list.
lng
The language of translations.

Examples: 

curl https://qtr.fs.al/rss-feed/en
curl https://qtranslate.fs.al/qtr/rss-feed/en

tweet

GET tweet/$lng
Return a random translation in a suitable form for the twitter. If the request header 'Accept: application/json' is set, then the output will be in JSON. This can be useful for adding your custom hashtags, url, etc.
lng
Language of translations.
GET qtr/tweet/[$lng]
Return a random string and its translations in a suitable form for the twitter (truncated to 100 characters).

Note: This can be used in combination with cli twitter clients and with cron to post random tweets about translations. See this script as an example: https://gitlab.com/q-translate/qtr_server/blob/master/utils/twitter.sh

Examples: 

curl -q -k https://qtr.fs.al/tweet/en
curl -q -k -H 'Accept: application/json' \
     https://qtr.fs.al/tweet/en | python -m json.tool

curl -q -k https://qtranslate.fs.al/qtr/tweet/en

autouser

GET auto/user/$lng/$str
Retrieve a JSON list of autocomplete suggestions for users.
lng
Language of translations.
str
Beginning of a user name.

Examples: 

curl https://qtr.fs.al/auto/user/sq/d

other

GET languages
Return a json list of languages installed on the system and their details.
GET chapters
Return a json list of the chapters and their details.

Examples: 

curl https://qtr.fs.al/languages | python -m json.tool
curl https://qtr.fs.al/chapters | python -m json.tool | less

oauth2

POST oauth2/token

Get an OAuth2 token. 

$.ajax(base_url + '/oauth2/token', {
    type: 'POST',
    data: {
        grant_type: 'password',
        username: 'user1',
        password: 'pass1',
        scope: 'user_profile', 
    },
    headers: {
        'Authorization': 'Basic ' + btoa(client_id + ':' + client_secret'), 
    },

});
GET oauth2/tokens/<access_token>

Verify the validity of an OAuth2 token. 

$.ajax(base_url + '/oauth2/tokens/' + access_token)
    .fail(function () {
        console.log('Token is not valid.');
    })
    .done(function (response) {
        console.log(response);
    });
POST oauth2/user/profile

Get the profile of the user. 

$.ajax(base_url + '/oauth2/user/profile', {
    type: 'POST',
    headers: {
        'Authorization': 'Bearer ' + access_token,
    },
    dataType: 'json',
});

Examples:

For more details and examples see: https://gitlab.com/dashohoxha/oauth2-js

For PHP examples see:

Author: Dashamir Hoxha

Created: 2016-08-07 Sun 14:19