Version at: 20/11/2022, 20:52 vs. version at: 22/11/2022, 02:09
11# API
22
33This page gives a few examples of how to use the Tatoeba API.
44
55## Retrieving a sentence with a known ID
66
77To retrieve sentence number 1:
88
99`https://tatoeba.org/eng/api_v0/sentence/1`
1010
1111## Search results
12
13### How to Construct a Call Based on an Advanced Search
14
15To figure out how to make a call to the API, you can perform an advanced search from the Tatoeba website, then change the first part of the URL from this:
16
17`https://tatoeba.org/en/sentences`
18
19to this:
20
21`https://tatoeba.org/eng/api_v0`
22
23For instance, if you use the advanced search interface to select English sentences without audio that contain the word "those", you will see that the URL looks like this:
24
25`https://tatoeba.org/en/sentences/search?from=eng&has_audio=no&native=&orphans=no&query=those&sort=relevance&sort_reverse=&tags=&to=&trans_filter=limit&trans_has_audio=&trans_link=&trans_orphan=&trans_to=&trans_unapproved=&trans_user=&unapproved=no&user=`
26
27Change the first part of the URL in order to produce this URL, which uses the API:
28
29`https://tatoeba.org/eng/api_v0/search?from=eng&has_audio=no&native=&orphans=no&query=those&sort=relevance&sort_reverse=&tags=&to=&trans_filter=limit&trans_has_audio=&trans_link=&trans_orphan=&trans_to=&trans_unapproved=&trans_user=&unapproved=no&user=`
1230
1331### Example 1
1432
1533Search: English sentences containing the word "Canadian" that have direct Japanese translations
1634
1735_Note that in English, unless the search string is preceded by an equals sign, the search will not be exact, so this query will also match "Canadians". For for more information, see "Main search field" in [How to Search for Text](text-search#)._
1836
1937 - from: **eng**
2038 - to: **jpn**
2139 - translations: **direct only**
2240
2341URL:
2442`https://tatoeba.org/eng/api_v0/search?from=eng&query=Canadian&trans_filter=limit&trans_link=direct&trans_to=jpn&to=jpn`
2543
2644### Example 2
2745
2846Search: English sentences containing the word "Boston" that have audio and Japanese translations (direct or indirect), sorted by creation date
2947
3048 - from: **eng**
3149 - to: **jpn**
3250 - audio: **yes**
3351 - sort: **by creation date**
3452 - translations: **direct and indirect**
3553
3654URL:
3755`https://tatoeba.org/eng/api_v0/search?from=eng&trans_filter=limit&query=Boston&sort=created&has_audio=yes&trans_to=jpn&to=jpn`
3856
3957### Example 3
4058
4159Search: English sentences containing the word "=play" (exact match) in list 907 that have direct translations in Japanese
4260
4361 - from: **eng**
4462 - to: **jpn**
4563 - list: **907**
4664 - sort: **words**
4765 - translations: **direct only**
4866
4967URL:
5068`https://tatoeba.org/eng/api_v0/search?from=eng&list=907&query=%3Dplay&sort=created&trans_filter=limit&trans_link=direct&trans_to=jpn&to=jpn`
5169
5270
53### How to Construct a Call Based on an Advanced Search
54
55To figure out how to make a call to the API, you can perform an advanced search from the Tatoeba website, then change the first part of the URL from this:
56
57`https://tatoeba.org/en/sentences`
58
59to this:
60
61`https://tatoeba.org/eng/api_v0`
62
63For instance, if you use the advanced search interface to select English sentences without audio that contain the word "those", you will see that the URL looks like this:
64
65`https://tatoeba.org/en/sentences/search?from=eng&has_audio=no&native=&orphans=no&query=those&sort=relevance&sort_reverse=&tags=&to=&trans_filter=limit&trans_has_audio=&trans_link=&trans_orphan=&trans_to=&trans_unapproved=&trans_user=&unapproved=no&user=`
66
67Change the first part of the URL in order to produce this URL, which uses the API:
68
69`https://tatoeba.org/eng/api_v0/search?from=eng&has_audio=no&native=&orphans=no&query=those&sort=relevance&sort_reverse=&tags=&to=&trans_filter=limit&trans_has_audio=&trans_link=&trans_orphan=&trans_to=&trans_unapproved=&trans_user=&unapproved=no&user=`
7071
7172## Paging
7273
7374You can use the count and perPage in the paging information to find out how many pages are contained in the search results. For instance, the following call:
7475
7576`https://dev.tatoeba.org/eng/api_v0/search?from=eng&list=907&query=Canadian&trans_filter=limit&trans_link=direct&trans_to=jpn&to=jpn&page=2`
7677
7778will produce the following result:
7879
7980 "paging": {
8081 "Sentences": {
8182 "finder": "all",
8283 "page": 2,
8384 "current": 8,
8485 "count": 18,
8586 "perPage": 10,
8687 "start": 11,
8788 "end": 18,
8889 "prevPage": true,
8990 "nextPage": false,
9091 "pageCount": 2,
9192 "sort": null,
9293 "direction": null,
9394 "limit": null,
9495 "sortDefault": false,
9596 "directionDefault": false,
9697 "scope": null,
9798 "completeSort": []
9899 }
99100 },
100101
101102
102103
103104The relevant properties are:
104105
105106 - `page`: current page
106107 - `current`: number of items displayed in the current page
107108 - `count`: total number of results
108109 - `perPage`: number of results per page
109110
110111To find the number of pages in total, divide `count` by `perPage` and round up to the nearest integer.
111112
112113
113114
114115
115116## For more information on the API
116117
117118See Tatoeba/tatoeba2 GitHub issue [#2669][1].
118119
119120 [1]: https://github.com/Tatoeba/tatoeba2/issues/2669
120121
diff view generated by jsdifflib

Version at: 20/11/2022, 20:52

# API

This page gives a few examples of how to use the Tatoeba API.

## Retrieving a sentence with a known ID

To retrieve sentence number 1:

`https://tatoeba.org/eng/api_v0/sentence/1`

## Search results

### Example 1

Search: English sentences containing the word "Canadian" that have direct Japanese translations

_Note that in English, unless the search string is preceded by an equals sign, the search will not be exact, so this query will also match "Canadians". For for more information, see "Main search field" in [How to Search for Text](text-search#)._

 - from: **eng**
 - to: **jpn**
 - translations: **direct only**

URL: 
`https://tatoeba.org/eng/api_v0/search?from=eng&query=Canadian&trans_filter=limit&trans_link=direct&trans_to=jpn&to=jpn`

### Example 2

Search: English sentences containing the word "Boston" that have audio and Japanese translations (direct or indirect), sorted by creation date

 - from: **eng**
 - to: **jpn**
 - audio: **yes**
 - sort: **by creation date**
 - translations: **direct and indirect**

URL: 
`https://tatoeba.org/eng/api_v0/search?from=eng&trans_filter=limit&query=Boston&sort=created&has_audio=yes&trans_to=jpn&to=jpn`

### Example 3

Search: English sentences containing the word "=play" (exact match) in list 907 that have direct translations in Japanese

 - from: **eng**
 - to: **jpn**
 - list: **907**
 - sort: **words**
 - translations: **direct only**

URL:
`https://tatoeba.org/eng/api_v0/search?from=eng&list=907&query=%3Dplay&sort=created&trans_filter=limit&trans_link=direct&trans_to=jpn&to=jpn`


### How to Construct a Call Based on an Advanced Search

To figure out how to make a call to the API, you can perform an advanced search from the Tatoeba website, then change the first part of the URL from this:

`https://tatoeba.org/en/sentences`

to this:

`https://tatoeba.org/eng/api_v0`

For instance, if you use the advanced search interface to select English sentences without audio that contain the word "those", you will see that the URL looks like this:

`https://tatoeba.org/en/sentences/search?from=eng&has_audio=no&native=&orphans=no&query=those&sort=relevance&sort_reverse=&tags=&to=&trans_filter=limit&trans_has_audio=&trans_link=&trans_orphan=&trans_to=&trans_unapproved=&trans_user=&unapproved=no&user=`

Change the first part of the URL in order to produce this URL, which uses the API:

`https://tatoeba.org/eng/api_v0/search?from=eng&has_audio=no&native=&orphans=no&query=those&sort=relevance&sort_reverse=&tags=&to=&trans_filter=limit&trans_has_audio=&trans_link=&trans_orphan=&trans_to=&trans_unapproved=&trans_user=&unapproved=no&user=`

## Paging

You can use the count and perPage in the paging information to find out how many pages are contained in the search results. For instance, the following call:

`https://dev.tatoeba.org/eng/api_v0/search?from=eng&list=907&query=Canadian&trans_filter=limit&trans_link=direct&trans_to=jpn&to=jpn&page=2`

will produce the following result:

    "paging": {
      "Sentences": {
        "finder": "all",
        "page": 2,
        "current": 8,
        "count": 18,
        "perPage": 10,
        "start": 11,
        "end": 18,
        "prevPage": true,
        "nextPage": false,
        "pageCount": 2,
        "sort": null,
        "direction": null,
        "limit": null,
        "sortDefault": false,
        "directionDefault": false,
        "scope": null,
        "completeSort": []
    }
  },



The relevant properties are:

 - `page`: current page
 - `current`: number of items displayed in the current page
 - `count`: total number of results
 - `perPage`: number of results per page

To find the number of pages in total, divide `count` by `perPage` and round up to the nearest integer.




## For more information on the API

See Tatoeba/tatoeba2 GitHub issue [#2669][1].

  [1]: https://github.com/Tatoeba/tatoeba2/issues/2669

version at: 22/11/2022, 02:09

# API

This page gives a few examples of how to use the Tatoeba API.

## Retrieving a sentence with a known ID

To retrieve sentence number 1:

`https://tatoeba.org/eng/api_v0/sentence/1`

## Search results

### How to Construct a Call Based on an Advanced Search

To figure out how to make a call to the API, you can perform an advanced search from the Tatoeba website, then change the first part of the URL from this:

`https://tatoeba.org/en/sentences`

to this:

`https://tatoeba.org/eng/api_v0`

For instance, if you use the advanced search interface to select English sentences without audio that contain the word "those", you will see that the URL looks like this:

`https://tatoeba.org/en/sentences/search?from=eng&has_audio=no&native=&orphans=no&query=those&sort=relevance&sort_reverse=&tags=&to=&trans_filter=limit&trans_has_audio=&trans_link=&trans_orphan=&trans_to=&trans_unapproved=&trans_user=&unapproved=no&user=`

Change the first part of the URL in order to produce this URL, which uses the API:

`https://tatoeba.org/eng/api_v0/search?from=eng&has_audio=no&native=&orphans=no&query=those&sort=relevance&sort_reverse=&tags=&to=&trans_filter=limit&trans_has_audio=&trans_link=&trans_orphan=&trans_to=&trans_unapproved=&trans_user=&unapproved=no&user=`

### Example 1

Search: English sentences containing the word "Canadian" that have direct Japanese translations

_Note that in English, unless the search string is preceded by an equals sign, the search will not be exact, so this query will also match "Canadians". For for more information, see "Main search field" in [How to Search for Text](text-search#)._

 - from: **eng**
 - to: **jpn**
 - translations: **direct only**

URL: 
`https://tatoeba.org/eng/api_v0/search?from=eng&query=Canadian&trans_filter=limit&trans_link=direct&trans_to=jpn&to=jpn`

### Example 2

Search: English sentences containing the word "Boston" that have audio and Japanese translations (direct or indirect), sorted by creation date

 - from: **eng**
 - to: **jpn**
 - audio: **yes**
 - sort: **by creation date**
 - translations: **direct and indirect**

URL: 
`https://tatoeba.org/eng/api_v0/search?from=eng&trans_filter=limit&query=Boston&sort=created&has_audio=yes&trans_to=jpn&to=jpn`

### Example 3

Search: English sentences containing the word "=play" (exact match) in list 907 that have direct translations in Japanese

 - from: **eng**
 - to: **jpn**
 - list: **907**
 - sort: **words**
 - translations: **direct only**

URL:
`https://tatoeba.org/eng/api_v0/search?from=eng&list=907&query=%3Dplay&sort=created&trans_filter=limit&trans_link=direct&trans_to=jpn&to=jpn`



## Paging

You can use the count and perPage in the paging information to find out how many pages are contained in the search results. For instance, the following call:

`https://dev.tatoeba.org/eng/api_v0/search?from=eng&list=907&query=Canadian&trans_filter=limit&trans_link=direct&trans_to=jpn&to=jpn&page=2`

will produce the following result:

    "paging": {
      "Sentences": {
        "finder": "all",
        "page": 2,
        "current": 8,
        "count": 18,
        "perPage": 10,
        "start": 11,
        "end": 18,
        "prevPage": true,
        "nextPage": false,
        "pageCount": 2,
        "sort": null,
        "direction": null,
        "limit": null,
        "sortDefault": false,
        "directionDefault": false,
        "scope": null,
        "completeSort": []
    }
  },



The relevant properties are:

 - `page`: current page
 - `current`: number of items displayed in the current page
 - `count`: total number of results
 - `perPage`: number of results per page

To find the number of pages in total, divide `count` by `perPage` and round up to the nearest integer.




## For more information on the API

See Tatoeba/tatoeba2 GitHub issue [#2669][1].

  [1]: https://github.com/Tatoeba/tatoeba2/issues/2669

Note

The lines in green are the lines that have been added in the new version. The lines in red are those that have been removed.