Version at: 22/11/2022, 02:09 vs. version at: 22/11/2022, 02:11
11# API
22
3This page gives a few examples of how to use the Tatoeba API.
3This page describes how to get started with 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
1212
1313### How to Construct a Call Based on an Advanced Search
1414
1515To 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:
1616
1717`https://tatoeba.org/en/sentences`
1818
1919to this:
2020
2121`https://tatoeba.org/eng/api_v0`
2222
2323For 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:
2424
2525`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=`
2626
2727Change the first part of the URL in order to produce this URL, which uses the API:
2828
2929`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=`
3030
3131### Example 1
3232
3333Search: English sentences containing the word "Canadian" that have direct Japanese translations
3434
3535_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#)._
3636
3737 - from: **eng**
3838 - to: **jpn**
3939 - translations: **direct only**
4040
4141URL:
4242`https://tatoeba.org/eng/api_v0/search?from=eng&query=Canadian&trans_filter=limit&trans_link=direct&trans_to=jpn&to=jpn`
4343
4444### Example 2
4545
4646Search: English sentences containing the word "Boston" that have audio and Japanese translations (direct or indirect), sorted by creation date
4747
4848 - from: **eng**
4949 - to: **jpn**
5050 - audio: **yes**
5151 - sort: **by creation date**
5252 - translations: **direct and indirect**
5353
5454URL:
5555`https://tatoeba.org/eng/api_v0/search?from=eng&trans_filter=limit&query=Boston&sort=created&has_audio=yes&trans_to=jpn&to=jpn`
5656
5757### Example 3
5858
5959Search: English sentences containing the word "=play" (exact match) in list 907 that have direct translations in Japanese
6060
6161 - from: **eng**
6262 - to: **jpn**
6363 - list: **907**
6464 - sort: **words**
6565 - translations: **direct only**
6666
6767URL:
6868`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`
6969
7070
7171
7272## Paging
7373
7474You 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:
7575
7676`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`
7777
7878will produce the following result:
7979
8080 "paging": {
8181 "Sentences": {
8282 "finder": "all",
8383 "page": 2,
8484 "current": 8,
8585 "count": 18,
8686 "perPage": 10,
8787 "start": 11,
8888 "end": 18,
8989 "prevPage": true,
9090 "nextPage": false,
9191 "pageCount": 2,
9292 "sort": null,
9393 "direction": null,
9494 "limit": null,
9595 "sortDefault": false,
9696 "directionDefault": false,
9797 "scope": null,
9898 "completeSort": []
9999 }
100100 },
101101
102102
103103
104104The relevant properties are:
105105
106106 - `page`: current page
107107 - `current`: number of items displayed in the current page
108108 - `count`: total number of results
109109 - `perPage`: number of results per page
110110
111111To find the number of pages in total, divide `count` by `perPage` and round up to the nearest integer.
112112
113113
114114
115115
116116## For more information on the API
117117
118118See Tatoeba/tatoeba2 GitHub issue [#2669][1].
119119
120120 [1]: https://github.com/Tatoeba/tatoeba2/issues/2669
121121
diff view generated by jsdifflib

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

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

# API

This page describes how to get started with 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.