General Information
This translation API by De Kok Translations brings high-quality translations to your application. Email us (api@dekok.com) to learn more and to get set up with a free trial account.
Authentication
All requests require an authentication key (email us to get one). To authenticate, set the Authorization header to Auth-Key [your Auth-Key] as demonstrated below.
Example curl
``` console
curl -X POST -H "Authorization: Auth-Key your-auth-key-goes-here:dk" \
https://api.dekok.com/usage
```
Example response
``` json
{
"characters_used": 123456,
"end_period": "01-02-2022",
"start_period": "01-01-2022"
}
```
Testing
A testing environment is made available at https://api-test.dekok.com/. This environment is identical to the production environment, except for already having any unreleased changes and a testing Auth-Key (request one). While there are no hard limits, performance may be worse than the production environment and logs may be used to determine fair use.
5 workdays before any changes that would affect how to interact with the API are deployed to api.dekok.com, these changes will be
- made available to you in the testing environment;
- communicated to the contact email of your account;
- included in the changelog at the bottom of this page.
Error Handling
Succesful requests return status code 200. Unsuccesful requests return one of the errors below. The response body may contain additional information on what went wrong.
Status codes
| Code | Description |
| ------------- |:-------------:|
| 200 | Succesful request |
| 400 | Invalid request. Check the response body and your request parameters |
| 403 | Unsuccesful authorization. There should be an *Authorization* header set to *Auth-Key your-auth-key-goes-here:dk* |
| 404 | Requested resource not found. Check the requested endpoint. |
| 503 | Internal error or timeout (happens after 30 seconds). Delay your next request so that the server can recover. Please get in touch if you consistently get a 503 status code so that we can investigate.
Status & Uptime
Current status and uptime statistics for the last 90 days are available on this page. This page may display that monitoring is switched off, this is done during scheduled maintenance windows to keep the uptime statistics accurate for comparison with specified service levels.
In addition, https://api.dekok.com/status is also available and will return a JSON response containing either {"status": "UP"} or {"status": "DOWN"}.
- All requests should be POST with Content-Type application/x-www-form-urlencoded).
- Note: most curl examples on this page do not explicitely specify POST and Content-Type, since the -d flag already implies this. However, depending on your implementation, you may need to explicitly specify this.
- Content-Length can't exceed 1,000,000 bytes (i.e. request body needs to be less than 1 mb).
- All language fields use ISO 639-1 language codes.
- Responses are in JSON.
- You can always email us for help or to suggest improvements.
Endpoints
POST /translate
Request Parameters
| Parameter | Required | Description |
| ------------- |:-------------:| -----:|
| text | Required | Text(s) to be translated. Can be repeated and can contain multiple sentences, but **all *text* fields must be of the same language.** For optimal performance, it is recommended to include around 50,000 characters per request.
| from | Optional* | The ISO 639-1 language code to translate from. Use the */languages* endpoint to see which languages are available for your account. Only one *from* field can be set. *If absent, the source language will be automatically determined at a performance cost (therefore it is recommended to set it when feasible). |
| to | Required | The ISO 639-1 language code to translate to. Use the */languages* endpoint to see which languages are available for your account.
Response
| Value | Description |
| ------------- |:-------------:|
| detected_source_language | The source language that was specified in the *from* field or the ISO 639-1 language code that was detected and translated from. |
| text | A list with the translated texts in the order of the request. Any characters reserved for JSON formatting are escaped (backspace > \b, form feed > \f, newline > \n, carriage return > \r, tab > \t, double quote > \\", backslash > \\\\).
Example
Request
``` console
curl https://api.dekok.com/translate
-H "Authorization: Auth-Key your-auth-key-goes-here:dk"
-d "from=ru"
-d "to=en"
-d "text=Эти переводы очень хороши."
-d "text=Вы можете установить несколько текстовых переменных.
Мы рекомендуем переводить до 50,000 символов или 5000 текстовых
переменных на запрос."
```
Response
``` json
{
"detected_source_language": "ru",
"text": [
"These translations are very good.",
"You can set several text variables.
We recommend translating up to 50,
000 characters or 5000 text
variables per request."
]
}
```
POST /usage
Returns the number of characters used in a certain month. Defaults to current month.
Request Parameters
| Parameter | Required | Description |
| ------------- |:-------------:| -----:|
| month | Optional | Number of the month (mm) to get the usage for. If left empty the current month is used. |
| year | Optional | Year (yyyy) to look up a certain month's usage for. If left empty the current year is used.
Response
| Value | Description |
| ------------- |:-------------:|
| characters_used | The number of characters succesfully translated within a period. Each unicode point within 'text' fields of succesful /translate requests counts as one character. |
| first_date_of_period | Usage is from this date (dd-mm-yyyy) up to to and including the laste_date_of_period. |
| last_date_of_period | Usage is from first_date_of_period up to and including this date (dd-mm-yyyy).
Example
Request
``` console
curl https://api.dekok.com/usage
-H "Authorization: Auth-Key your-auth-key-goes-here:dk"
-d "year=2021"
-d "month=12"
```
Response
``` json
{
"characters_used": 123456,
"first_date_of_period": "01-12-2021",
"last_date_of_period": "31-12-2021"
}
```
POST /languages
Returns the languages that are available to translate to and from. Does not take any parameters (but still requires the Authorization header as it is account based). Additional languages are available upon request.
Response
| Value | Description |
| ------------- |:-------------:|
| languages | A list of available languages to translate to and from.
Example
Request
``` console
curl https://api.dekok.com/languages
-H "Authorization: Auth-Key your-auth-key-goes-here:dk"
```
Response
``` json
{
"languages": [
"ru",
"uk",
"es",
"en",
"nl"
]
}
```
Changelog
| Date | Environment | Description |
| ------------- |:-------------:| -----:|
| 09/09/2022 | api.dekok.com | Bug fixes |
| 11/10/2022 | api.dekok.com | Added section Status & Uptime |
| 24/10/2022 | api.dekok.com | Response body now properly escapes JSON reserved characters |