Every API call must be authorized using an API key. While you’re testing, you should use the sandbox and generate your keys from there. In this tutorial I will show you how to create a sandbox account, so that you can get your API keys to make calls to the Gengo Translate API.
First you need to create a free sandbox account.
After logging in, go to your Account section, and click on “API settings” in the right-hand menu.
This is where your API keys will be stored. To create a new key, click “Generate Key”.
Each public key has a corresponding private key and callback URL. The public key is what identifies you - like your login name. The private key is like your password - do NOT share it with anyone, or they may be able to access your account. The callback URL is helpful if you want Gengo to send status updates about the progress of your job to your server or application.
Copy the public and private keys so you can use them in your application.
1 2 3 4 5 | #!/usr/bin/python
# -*- coding: utf-8 -*-
PUBLIC_KEY = 'rspZJxEnswelpvS0)tdwM]7uPjkcgR%@k_mN[Z1ac_3a=#EN%r=]cKwxq98-XQdK'
PRIVATE_KEY = 'IlUyZP5TISBSxRzEm0mil$L}-0FxeX(24W1d#TkY{qNkh42Q3B}m2)XJi_nYqrl^'
|
That’s it! In the next step we’ll show some API calls in action.
In this tutorial I will demonstrate how to make API calls using some command-line Python scripts. In all examples, we’ll assume the following constant values:
1 2 3 4 5 6 7 8 | #!/usr/bin/python
# -*- coding: utf-8 -*-
PUBLIC_KEY = 'your public key'
PRIVATE_KEY = 'your private key'
URL = 'http://api.sandbox.gengo.com/v2/'
RESPONSE_TYPE = 'json'
header = {"Accept": "application/{0}".format(RESPONSE_TYPE)}
|
First we’ll make a simple call to retrieve a list of translation language pairs.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 | #!/usr/bin/python
# -*- coding: utf-8 -*-
from hashlib import sha1
import hmac
import json
import requests
import time
if __name__ == '__main__':
PUBLIC_KEY = 'your public key'
PRIVATE_KEY = 'your private key'
URL = "http://api.gengo.com/v2/translate/service/language_pairs"
header = {"Accept": "application/json"}
data = {
"api_key": PUBLIC_KEY,
"ts": str(int(time.time()))
}
# use your private_key to create an hmac
data["api_sig"] = hmac.new(
PRIVATE_KEY,
data["ts"],
sha1
).hexdigest()
get_language_pair = requests.get(URL, headers=header, params=data)
res_json = json.loads(get_language_pair.text)
if res_json["opstat"] != "ok":
msg = "API error occured.\nerror msg: {0}".format(
res_json["err"]
)
raise AssertionError(msg)
else:
print(res_json)
|
Return value:
{
"opstat": "ok",
"response": [
{
"tier": "standard",
"lc_tgt": "en",
"lc_src": "de",
"unit_price": 0.05,
"currency": "USD"
},
{
"tier": "pro",
"lc_tgt": "en",
"lc_src": "de",
"unit_price": 0.10,
"currency": "USD"
},
...
...
...,
{
"tier": "pro",
"lc_tgt": "en",
"lc_src": "pt-br",
"unit_price": 0.10,
"currency": "USD"
}
]
}
What we get back is data about each supported language pair, including the quality level (or tier) and unit price.
So, that’s a very simple example of how to retrieve data through the Gengo Translate API.
Now let’s submit some jobs for human translation. The sandbox allows users to quickly add fake credits so you can easily submit jobs. First, login and add some fake credits to your account.
Once that’s done, open the example jobs-post.py script and edit fields for two jobs to submit. Add some text to have translated in the ‘body_src’ field, and check that the source, target, and tier parameters are what we want. We can also send some custom data to associate with each job; this is data specific to your service and won’t be touched at any time. Custom data will be returned verbatim whenever the job is requested.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 | #!/usr/bin/python
# -*- coding: utf-8 -*-
from hashlib import sha1
import hmac
import json
import requests
import time
if __name__ == '__main__':
PUBLIC_KEY = 'your public key'
PRIVATE_KEY = 'your private key'
URL = "http://api.gengo.com/v2/translate/jobs"
header = {"Accept": "application/json"}
data = {
"api_key": PUBLIC_KEY,
"ts": str(int(time.time()))
}
# use your private_key to create an hmac
data["api_sig"] = hmac.new(
PRIVATE_KEY,
data["ts"],
sha1
).hexdigest()
job1 = {
'slug': 'job test 1',
'body_src': 'one two three four',
'lc_src': 'en',
'lc_tgt': 'ja',
'tier': 'standard',
'auto_approve': 1,
'custom_data': 'some custom data untouched by Gengo.',
}
job2 = {
'slug': 'job test 2',
'body_src': 'five six seven eight',
'lc_src': 'en',
'lc_tgt': 'ja',
'tier': 'standard',
'comment': 'This one has a comment',
}
jobs = {'job_1': job1, 'job_2': job2}
data["data"] = json.dumps({'jobs': jobs}, separators=(',', ':'))
post_job = requests.post(URL, data=data, headers=header)
res_json = json.loads(post_job.text)
if not res_json["opstat"] != "ok":
msg = "API error occured.\nerror msg: {0}".format(
res_json["err"]
)
raise AssertionError(msg)
else:
print(res_json)
|
You’ll want to review documentation for the “translate/jobs” entry-point to see what other parameters are available.
So, let’s post these two jobs:
python jobs-post.py
The response will let you know various statistics about the order:
1 2 3 4 5 6 7 8 9 | {
"opstat": "ok",
"response": {
"order_id": 914451,
"job_count": 2,
"credits_used": 0.40,
"currency": "USD"
}
}
|
In the response from a job post, one of the most important pieces of info is the order id, which can be used to retrieve information about the order, such as the job ids of the jobs placed.