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

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

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

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

Actions

• History
• Revert to version made the 22/11/2022, 02:26
• Go back to article's page