Version at: 16/06/2021, 00:47 vs. version at: 20/11/2022, 20:31
11# API
22
3Briefly, ...
3This page gives a few examples of how to use the Tatoeba API.
44
55## For one sentence
66
7https://tatoeba.org/eng/api_v0/sentence/1
7To retrieve sentence number 1:
8
9 https://tatoeba.org/eng/api_v0/sentence/1
810
911## Search results
1012
11### Search: Canadian (not an exact match, so gets "Canadians", too.)
12from: eng
13to: jpn
14list: 907
15direct translations only
13### Search: "Canadian" (not an exact match, so also matches "Canadians")
14from: **eng**
15to: **jpn**
16list: **907**
17translations: **direct only**
1618
17https://tatoeba.org/eng/api_v0/search?from=eng&list=907&query=Canadian&trans_filter=limit&trans_link=direct&trans_to=jpn&to=jpn
19 https://tatoeba.org/eng/api_v0/search?from=eng&list=907&query=Canadian&trans_filter=limit&trans_link=direct&trans_to=jpn&to=jpn
1820
19### Search: Boston
20from: eng
21to: jpn
22audio: yes
23sort: created
24(direct and indirect translations)
21### Search: "Boston"
22from: **eng**
23to: **jpn**
24audio: **yes**
25sort: **by creation date**
26translations: **direct and indirect**
2527
26https://tatoeba.org/eng/api_v0/search?from=eng&trans_filter=limit&query=Boston&sort=created&has_audio=yes&trans_to=jpn&to=jpn
28 https://tatoeba.org/eng/api_v0/search?from=eng&trans_filter=limit&query=Boston&sort=created&has_audio=yes&trans_to=jpn&to=jpn
2729
28### Search: =play (exact match)
29from: eng
30to: jpn
31list: 907
32sort: words
33direct translations only
30### Search: "=play" (exact match)
31from: **eng**
32to: **jpn**
33list: **907**
34sort: **words**
35translations: **direct only**
3436
35https://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
37 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
3638
3739
3840### Other
3941
40Do an advanced search, copy the resulting URL and change the first part of the URL to match the first part of the API URL.
42To figure out how to make a call to the API, perform an advanced search, then change the first part of the URL from this:
4143
42https://tatoeba.org/en/sentences/advanced_search
44 https://tatoeba.org/en/sentences
45
46to this:
47
48 https://tatoeba.org/eng/api_v0
49
50For 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:
51
52 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=
53
54Change the first part of the URL in order to produce this URL that can be called against the API:
55
56 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=
4357
4458## Paging
4559
46You can find out how many pages there thanks to the count and the perPage in the paging information.
60You 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:
4761
48https://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
62 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
4963
50 "paging": {
51 "Sentences": {
52 "finder": "all",
53 "page": 2,
54 "current": 8,
55 "count": 18,
56 "perPage": 10,
57 "start": 11,
58 "end": 18,
59 "prevPage": true,
60 "nextPage": false,
61 "pageCount": 2,
62 "sort": null,
63 "direction": null,
64 "limit": null,
65 "sortDefault": false,
66 "directionDefault": false,
67 "scope": null,
68 "completeSort": []
64will produce the following result:
65
66 "paging": {
67 "Sentences": {
68 "finder": "all",
69 "page": 2,
70 "current": 8,
71 "count": 18,
72 "perPage": 10,
73 "start": 11,
74 "end": 18,
75 "prevPage": true,
76 "nextPage": false,
77 "pageCount": 2,
78 "sort": null,
79 "direction": null,
80 "limit": null,
81 "sortDefault": false,
82 "directionDefault": false,
83 "scope": null,
84 "completeSort": []
6985 }
7086 },
7187
7288
7389
74The properties you'll be interested in are:
90The relevant properties are:
7591
76page - this is the current page.
77current - this is the number of items displayed in the current page.
78count - this is the total number of results.
79perPage - this is the number of results per page.
80To know how many pages there are in total, you divide count by perPage and round up to the upper integer.
92 - `page`: current page
93 - `current`: number of items displayed in the current page
94 - `count`: total number of results
95 - `perPage`: number of results per page
96
97To find the number of pages in total, divide `count` by `perPage` and round up to the nearest integer.
8198
8299
83100
84101
85## For information on the API, ...
102## For more information on the API
86103
87See https://github.com/Tatoeba/tatoeba2/issues/2669
104See Tatoeba/tatoeba2 GitHub issue [#2669][1].
88105
106 [1]: https://github.com/Tatoeba/tatoeba2/issues/2669
89107
90
diff view generated by jsdifflib

Version at: 16/06/2021, 00: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/2022, 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.