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

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

# API

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

## For one sentence

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: 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

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.