Version at: 07/10/2023, 03:20 vs. version at: 12/02/2025, 03:22
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
3333Search: English sentences containing the word "play".
3434
3535_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#)._
3636
3737 - query: **=play**
3838 - from: **eng**
3939
4040URL:
4141`https://tatoeba.org/eng/api_v0/search?from=eng&query=%3Dplay`
4242
4343### Example 2
4444
4545Search: English sentences containing the word "Canadian", "Canadians", etc., that have direct Japanese translations
4646
4747 - query: **Canadian**
4848 - from: **eng**
4949 - to: **jpn**
5050 - translations: **direct only**
5151
5252URL:
5353`https://tatoeba.org/eng/api_v0/search?from=eng&query=Canadian&trans_filter=limit&trans_link=direct&trans_to=jpn&to=jpn`
5454
5555### Example 3
5656
5757Search: English sentences in list 907 containing the word "Boston" that have audio and Japanese translations (direct or indirect), sorted by creation date
5858
5959 - query: **Boston**
6060 - from: **eng**
6161 - to: **jpn**
6262 - audio: **yes**
6363 - list: **907**
6464 - sort: **by creation date**
6565 - translations: **direct and indirect**
6666
6767URL:
6868`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`
6969
7070## Paging
7171
7272You 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:
7373
7474`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`
7575
7676will produce the following result:
7777
7878 "paging": {
7979 "Sentences": {
8080 "finder": "all",
8181 "page": 2,
8282 "current": 8,
8383 "count": 18,
8484 "perPage": 10,
8585 "start": 11,
8686 "end": 18,
8787 "prevPage": true,
8888 "nextPage": false,
8989 "pageCount": 2,
9090 "sort": null,
9191 "direction": null,
9292 "limit": null,
9393 "sortDefault": false,
9494 "directionDefault": false,
9595 "scope": null,
9696 "completeSort": []
9797 }
9898 },
9999
100100
101101
102102The relevant properties are:
103103
104104 - `page`: current page
105105 - `current`: number of items displayed in the current page
106106 - `count`: total number of results
107107 - `perPage`: number of results per page
108108
109109To find the number of pages in total, divide `count` by `perPage` and round up to the nearest integer.
110110
111111
112112
113113
114114## GitHub issue
115115
116116GitHub issue [#2669][1] contains discussion of the API, beginning with the initial proposal.
117117
118118 * [https://github.com/Tatoeba/tatoeba2/issues/2669](https://github.com/Tatoeba/tatoeba2/issues/2669)
119119
120120## Also read ....
121121
122122 * [Using the Tatoeba Corpus for Your Own Projects](https://en.wiki.tatoeba.org/articles/show/using-the-tatoeba-corpus)
123123
124* [api.dev.tatoeba.org](https://api.dev.tatoeba.org/)
124 * A new API is being developed at [api.tatoeba.org](https://api.tatoeba.org/)
125125
diff view generated by jsdifflib

Version at: 07/10/2023, 03:20

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




## GitHub issue

GitHub issue [#2669][1] contains discussion of the API, beginning with the initial proposal.

  * [https://github.com/Tatoeba/tatoeba2/issues/2669](https://github.com/Tatoeba/tatoeba2/issues/2669)

## Also read ....

 * [Using the Tatoeba Corpus for Your Own Projects](https://en.wiki.tatoeba.org/articles/show/using-the-tatoeba-corpus)

* [api.dev.tatoeba.org](https://api.dev.tatoeba.org/)

version at: 12/02/2025, 03: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". 

_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.




## GitHub issue

GitHub issue [#2669][1] contains discussion of the API, beginning with the initial proposal.

  * [https://github.com/Tatoeba/tatoeba2/issues/2669](https://github.com/Tatoeba/tatoeba2/issues/2669)

## Also read ....

 * [Using the Tatoeba Corpus for Your Own Projects](https://en.wiki.tatoeba.org/articles/show/using-the-tatoeba-corpus)

 * A new API is being developed at [api.tatoeba.org](https://api.tatoeba.org/)

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.

Actions