-
Notifications
You must be signed in to change notification settings - Fork 0
Usage examples
The following example will show you how to use the TEXTKING Translation API to calculate the price for a translation and order that translation from TEXTKING. Before you get started see Authorization and authentication on how to register for the API and obtain an Access Token. You will need the Access Token to perform the API requests below.
The example will show you the necessary HTTP requests for each task. You can use the tool or programming language of your choice to actually perform those HTTP requests. For a quick testing you can use the browser add-ons cRest Client for Google Chrome or RESTClient for Firefox.
For this example we will show you how to translate a simple text document from English to French.
The first step to get your translation is to create an translation project on TEXTKING. A translation project can hold multiple jobs, each job representing one document to be translated into one target language. To create a project use the following POST request to /v1/projects:
POST /v1/projects HTTP/1.1
Host: api.textking.com
Accept: application/json
Content-Type: application/json
Authorization: Bearer youraccesstoken
{
"name": "My Translation Project",
}
You can give the project any name you want. Upon success the API will respond with a status code of 201 Created and include the newly created project in the response body. This response will also tell you the ID of the project and the direct URL to the project itself.
HTTP/1.1 201 Created
Content-Type: application/json; charset=utf-8
Location: https://api.textking.com/v1/project/29163f4f-7c8f-4baf-adf3-753c1df429c2
Content-Location: https://api.textking.com/v1/project/29163f4f-7c8f-4baf-adf3-753c1df429c2
{
"id": "29163f4f-7c8f-4baf-adf3-753c1df429c2",
"number": null,
"name": "My Translation Project",
"due_date": null,
"state": "prepared",
"currency": "EUR",
"net_price": null,
"vat": null,
"coupon_name": null,
"coupon_value": null,
"discount_customer": null,
"discount_project": null,
"affiliate_id": null,
"billing_address": "9c6f23b6-167d-4b01-977f-4de799e3abf3",
"links": [
{
"rel": "self",
"href": "https://api.textking.com/v1/project/29163f4f-7c8f-4baf-adf3-753c1df429c2"
},
{
"rel": "urn:textking:jobs",
"href": "https://api.textking.com/v1/project/29163f4f-7c8f-4baf-adf3-753c1df429c2/jobs"
},
{
"rel": "urn:textking:line_items",
"href": "https://api.textking.com/v1/project/29163f4f-7c8f-4baf-adf3-753c1df429c2/line-items"
},
{
"rel": "urn:textking:billing_address",
"href": "https://api.textking.com/v1/account/address/9c6f23b6-167d-4b01-977f-4de799e3abf3"
}
]
}
Now we have to add a new job to the project. For this use the POST request to v1/project/{projectId}/jobs below, but make sure to adjust the project ID in the request URL to the one you got when creating the project. You can find out more about the allowed values for the source and target language and the topic area by inspecting the /v1/languages/source, /v1/languages/target and /v1/topics resources. For the example we use the topic area “General” with the ID 49353ab0-fdbf-4e1c-a063-cdf4aad98782. For an actual translation you should choose the most appropriate topic area for your type of text.
POST /v1/project/29163f4f-7c8f-4baf-adf3-753c1df429c2/jobs HTTP/1.1
Host: api.textking.com
Accept: application/json
Content-Type: application/json
Authorization: Bearer youraccesstoken
{
"name": "My new translation job DE -> EN",
"source_language": "en",
"target_language": "fr",
"quality": "translation-and-correction",
"topic": "49353ab0-fdbf-4e1c-a063-cdf4aad98782",
"briefing": "Some remarks for the translator"
}
You will again get the created job in the response body:
HTTP/1.1 201 Created
Content-Type: application/json; charset=utf-8
Location: https://api.textking.com/v1/project/29163f4f-7c8f-4baf-adf3-753c1df429c2/job/3bfaa57a-7385-4fec-ae1a-ba2c6bea5679
Content-Location: https://api.textking.com/v1/project/29163f4f-7c8f-4baf-adf3-753c1df429c2/job/3bfaa57a-7385-4fec-ae1a-ba2c6bea5679
{
"id": "3bfaa57a-7385-4fec-ae1a-ba2c6bea5679",
"number": null,
"name": "My new translation job DE -> EN",
"source_language": "fr",
"target_language": "en",
"quality": "translation",
"topic": "49353ab0-fdbf-4e1c-a063-cdf4aad98782",
"briefing": "Some remarks for the translator",
"state": "new",
"words": null,
"net_price": null,
"currency": null,
"is_active": true,
"links": [
{
"rel": "self",
"href": "https://api.textking.com/v1/project/29163f4f-7c8f-4baf-adf3-753c1df429c2/job/3bfaa57a-7385-4fec-ae1a-ba2c6bea5679"
},
{
"rel": "urn:textking:project",
"href": "https://api.textking.com/v1/project/29163f4f-7c8f-4baf-adf3-753c1df429c2"
},
{
"rel": "urn:textking:topic",
"href": "https://api.textking.com/v1/topic/49353ab0-fdbf-4e1c-a063-cdf4aad98782"
}
]
}
The translation job we have added just sets the basic parameters for the translation, such as the languages and the topic area. But we still have to provide an actual text to be translated. In the following request we upload a plain text document with the file name “MyFile.txt”, but TEXTKING supports a variety of other file formats, including Microsoft Office (.doc, .docx, .xls, .xlsx, .pptx), Open Document (.odt), Adobe Indesign (.idml) and HTML and XML.
To add a file, just POST it to the /document resource of the job we created previously. The document itself is included in the request body. Make sure to set a sensible file name in the URL and include a correct Content-Type header.
POST /v1/project/29163f4f-7c8f-4baf-adf3-753c1df429c2/job/3bfaa57a-7385-4fec-ae1a-ba2c6bea5679/document/MyFile.txt HTTP/1.1 Host: api.textking.com Content-Type: text/plain Authorization: Bearer youraccesstoken Either the well was very deep, or she fell very slowly, for she had plenty of time as she went down to look about her, and to wonder what was going to happen next. First, she tried to look down and make out what she was coming to, but it was too dark to see anything: then she looked at the sides of the well, and noticed that they were filled with cupboards and book-shelves: here and there she saw maps and pictures hung upon pegs. She took down a jar from one of the shelves as she passed: it was labelled “ORANGE MARMALADE,” but to her great disappointment it was empty: she did not like to drop the jar, for fear of killing somebody underneath, so managed to put it into one of the cupboards as she fell past it.
The following response will tell you, that the document has been successfully uploaded:
HTTP/1.1 201 Created Location: https://api.textking.com/v1/project/29163f4f-7c8f-4baf-adf3-753c1df429c2/job/3bfaa57a-7385-4fec-ae1a-ba2c6bea5679/document Content-Location: https://api.textking.com/v1/project/29163f4f-7c8f-4baf-adf3-753c1df429c2/job/3bfaa57a-7385-4fec-ae1a-ba2c6bea5679/document
To check the costs of your translation project just use a GET request on the /project/{projectId} resource after you have added all jobs and documents you wish to be translated.
GET /v1/project/9f7f369f-670b-4bc0-8925-0344bfb68b70 HTTP/1.1 Host: api.textking.com Accept: application/json Authorization: Bearer youraccesstoken
The response will contain the complete translation costs. See the fields net_price, vat (value in percentage of the net price) and currency.
HTTP/1.1 200 Ok
Content-Type: application/json; charset=utf-8
{
"id": "9f7f369f-670b-4bc0-8925-0344bfb68b70",
"number": "EN1216954",
"name": "My Translation Project",
"due_date": "2012-10-22T00:00:00",
"state": "running",
"currency": "EUR",
"net_price": 19.4,
"vat": 8,
"coupon_name": null,
"coupon_value": null,
"discount_customer": 0,
"discount_project": 0,
"affiliate_id": null,
"billing_address": "9c6f23b6-167d-4b01-977f-4de799e3abf3",
"links": [
{
"rel": "self",
"href": "https://api.textking.com/v1/project/9f7f369f-670b-4bc0-8925-0344bfb68b70"
},
{
"rel": "urn:textking:jobs",
"href": "https://api.textking.com/v1/project/9f7f369f-670b-4bc0-8925-0344bfb68b70/jobs"
},
{
"rel": "urn:textking:line_items",
"href": "https://api.textking.com/v1/project/9f7f369f-670b-4bc0-8925-0344bfb68b70/line-items"
},
{
"rel": "urn:textking:billing_address",
"href": "https://api.textking.com/v1/account/address/9c6f23b6-167d-4b01-977f-4de799e3abf3"
}
]
}
In order to start a translation the state of the translation project must be set to running.
Be careful, setting the project state to running will actually inform our project management to accept and carry out your translation order. To avoid being billed while testing the service please contact us beforehand.
To update the project state send a PUT request to the project resource:
PUT /v1/project/29163f4f-7c8f-4baf-adf3-753c1df429c2 HTTP/1.1
Host: api.textking.com
Accept: application/json
Content-Type: application/json
Authorization: Bearer youraccesstoken
{
"due_date": "2012-11-17",
"state": "running"
}
The response body contains the updated project. If you want to cancel the project instead of starting it set the state to canceled.