Version at: 16/6/21 0:47

# API

Briefly, ...

## For one sentence

https://tatoeba.org/eng/api_v0/sentence/1

## Search results

### Search: Canadian (not an exact match, so gets "Canadians", too.)
from: eng
to: jpn
list: 907
direct translations only

https://tatoeba.org/eng/api_v0/search?from=eng&list=907&query=Canadian&trans_filter=limit&trans_link=direct&trans_to=jpn&to=jpn

### Search: Boston
from: eng
to: jpn
audio: yes
sort: created
(direct and indirect translations)

https://tatoeba.org/eng/api_v0/search?from=eng&trans_filter=limit&query=Boston&sort=created&has_audio=yes&trans_to=jpn&to=jpn

### Search: =play (exact match)
from: eng
to: jpn
list: 907
sort: words
direct translations only

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


### Other

Do an advanced search, copy the resulting URL and change the first part of the URL to match the first part of the API URL.

https://tatoeba.org/en/sentences/advanced_search

## Paging

You can find out how many pages there thanks to the count and the perPage in the paging information.

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

  "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 properties you'll be interested in are:

page - this is the current page.
current - this is the number of items displayed in the current page.
count - this is the total number of results.
perPage - this is the number of results per page.
To know how many pages there are in total, you divide count by perPage and round up to the upper integer.




## For information on the API, ...

See https://github.com/Tatoeba/tatoeba2/issues/2669


version at: 20/11/22 20:31

# 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

### Search: "Canadian" (not an exact match, so also matches "Canadians")
from: **eng**
to: **jpn**
list: **907**
translations: **direct only**

    https://tatoeba.org/eng/api_v0/search?from=eng&list=907&query=Canadian&trans_filter=limit&trans_link=direct&trans_to=jpn&to=jpn

### Search: "Boston"
from: **eng**
to: **jpn**
audio: **yes**
sort: **by creation date**
translations: **direct and indirect**

    https://tatoeba.org/eng/api_v0/search?from=eng&trans_filter=limit&query=Boston&sort=created&has_audio=yes&trans_to=jpn&to=jpn

### Search: "=play" (exact match)
from: **eng**
to: **jpn**
list: **907**
sort: **words**
translations: **direct only**

    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


### Other

To figure out how to make a call to the API, perform an advanced search, 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 that can be called against 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.