Version at: 22/11/2022, 02:22 vs. version at: 22/11/2022, 02:26
11# API
22
33This 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
33Search: English sentences containing the word "=play", where the equals sign (represented by "%3D" in the URL) is necessary in order to specify an exact match. _(For more information about specifying exact matches, see "Main search field" in [How to Search for Text](text-search#).)_
33Search: English sentences containing the word "play".
3434
35_Note: The equals sign, represented by "%3D" in the URL, is necessary in order to specify an exact match in English and several other languages. For more information about specifying exact matches, see "Main search field" in [How to Search for Text](text-search#)._
36
37 - query: **=play**
3538 - from: **eng**
36 - sort: **words**
3739
3840URL:
3941`https://tatoeba.org/eng/api_v0/search?from=eng&query=%3Dplay`
4042
4143### Example 2
4244
4345Search: English sentences containing the word "Canadian", "Canadians", etc., that have direct Japanese translations
4446
47 - query: **Canadian**
4548 - from: **eng**
4649 - to: **jpn**
4750 - translations: **direct only**
4851
4952URL:
5053`https://tatoeba.org/eng/api_v0/search?from=eng&query=Canadian&trans_filter=limit&trans_link=direct&trans_to=jpn&to=jpn`
5154
5255### Example 3
5356
5457Search: English sentences in list 907 containing the word "Boston" that have audio and Japanese translations (direct or indirect), sorted by creation date
5558
59 - query: **Boston**
5660 - from: **eng**
5761 - to: **jpn**
5862 - audio: **yes**
5963 - list: **907**
6064 - sort: **by creation date**
6165 - translations: **direct and indirect**
6266
6367URL:
6468`https://tatoeba.org/eng/api_v0/search?from=eng&trans_filter=limit&query=Boston&sort=created&has_audio=yes&list=907&trans_to=jpn&to=jpn`
6569
6670## Paging
6771
6872You 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:
6973
7074`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`
7175
7276will produce the following result:
7377
7478 "paging": {
7579 "Sentences": {
7680 "finder": "all",
7781 "page": 2,
7882 "current": 8,
7983 "count": 18,
8084 "perPage": 10,
8185 "start": 11,
8286 "end": 18,
8387 "prevPage": true,
8488 "nextPage": false,
8589 "pageCount": 2,
8690 "sort": null,
8791 "direction": null,
8892 "limit": null,
8993 "sortDefault": false,
9094 "directionDefault": false,
9195 "scope": null,
9296 "completeSort": []
9397 }
9498 },
9599
96100
97101
98102The relevant properties are:
99103
100104 - `page`: current page
101105 - `current`: number of items displayed in the current page
102106 - `count`: total number of results
103107 - `perPage`: number of results per page
104108
105109To find the number of pages in total, divide `count` by `perPage` and round up to the nearest integer.
106110
107111
108112
109113
110114## For more information on the API
111115
112116See Tatoeba/tatoeba2 GitHub issue [#2669][1].
113117
114118 [1]: https://github.com/Tatoeba/tatoeba2/issues/2669
115119
diff view generated by jsdifflib

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

# 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 "=play", where the equals sign (represented by "%3D" in the URL) is necessary in order to specify an exact match. _(For more information about specifying exact matches, see "Main search field" in [How to Search for Text](text-search#).)_

 - from: **eng**
 - sort: **words**

URL:
`https://tatoeba.org/eng/api_v0/search?from=eng&query=%3Dplay`

### Example 2

Search: English sentences containing the word "Canadian", "Canadians", etc., that have direct Japanese translations

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

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

 - from: **eng**
 - to: **jpn**
 - audio: **yes**
 - list: **907**
 - 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&list=907&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:26

# 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 "play". 

_Note: The equals sign, represented by "%3D" in the URL, is necessary in order to specify an exact match in English and several other languages. For more information about specifying exact matches, see "Main search field" in [How to Search for Text](text-search#)._

 - query: **=play**
 - from: **eng**

URL:
`https://tatoeba.org/eng/api_v0/search?from=eng&query=%3Dplay`

### Example 2

Search: English sentences containing the word "Canadian", "Canadians", etc., that have direct Japanese translations

 - query: **Canadian**
 - 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 3

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

 - query: **Boston**
 - from: **eng**
 - to: **jpn**
 - audio: **yes**
 - list: **907**
 - 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&list=907&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.