Home | Blog | What is TM-Town? | Directory Search | Nakōdo Expert Finder | Terminology Marketplace | Register | Log In

API

Getting Started

Welcome to the TM-Town API. The TM-Town API is a REST-like API for interacting with various TM-Town services. The TM-Town API includes both authentication through an API key (for publicly available data) as well as OAuth2 authentication for accessing TM-Town on behalf of different users. There is also a portion of the TM-Town API that is open and does not require an API key.

This API is still under development, but we are working hard to improve it! Please contact us if you run into trouble.

Authentication

A portion of the TM-Town API is open and no API key or authentication is needed. Other end points utilize the OAuth2 protocol.

All API requests must be made over HTTPS. Calls made over plain HTTP will fail.

OAuth2

OAuth2 is a standard protocol for secure authorization and authentication, commonly used for RESTful APIs. It allows users to authorize your application to use TM-Town on their behalf, without having to share sensitive login information. Find out how to register an OAuth2 application on TM-Town below.

Errors

TM-Town uses conventional HTTP response codes to indicate success or failure of an API request. In general, codes in the 2xx range indicate success, codes in the 4xx range indicate an error that resulted from the provided information (e.g. a required parameter was missing), and codes in the 5xx range indicate an error with TM-Town's servers.

Code Name Description
200 OK Everything worked successfully!
400 Bad Request Often missing a required parameter.
401 Unauthorized No valid API key or OAuth token provided.
402 Request Failed Parameters were valid but request failed.
404 Not Found The requested item doesn't exist.
500, 502, 503, 504 Server Errors Something went wrong on TM-Town's end.

Open Endpoints

Countries

/countries

TM-Town's Countries API is an open endpoint where you can query any of the countries in the TM-Town database.

Request Parameters
query
REQUIRED		 A query to search the name of any country in the database
Response
id The id of the record in TM-Town's database
name The name of the country
link A link to the TM-Town page for that country
iso_3166_1_alpha_2_code The ISO 3166-1 alpha-2 two-letter code for the country
iso_3166_1_alpha_3_code The ISO 3166-1 alpha-3 three-letter code for the country (if available)

Fields

/fields

TM-Town's Fields API is an open endpoint where you can query any of the fields of expertise in the TM-Town database.

Request Parameters
query
REQUIRED		 A query to search the name of any field of expertise in the database
Response
id The id of the record in TM-Town's database
name The name of the field of expertise
slug The URL slug of the field of expertise
document_count The number of documents tagged with that field of expertise
translation_unit_count The number of translation units tagged with that field of expertise
link A link to the TM-Town page for that field of expertise

Languages

/languages

TM-Town's Languages API is an open endpoint where you can query any of the ISO 639 listed languages. ISO 639 is a set of standards by the International Organization for Standardization that is concerned with representation of names for language and language groups. Languages that do not have an ISO 639-1 code are not included in the results.

Request Parameters
query
REQUIRED		 A query to search the English names of any of the languages in the database
Response
id The id of the record in TM-Town's database
name The English name of the language
link A link to the TM-Town page for that language
iso_639_1_code The ISO 639-1 two-letter code for the language (if available)
iso_639_2b_code The ISO 639-2b three-letter code for the language (if available)
iso_639_3_code The ISO 639-3 three-letter code for the language (if available)
alternate_names A hash of alternate names for the language including: native, french, spanish, chinese, russian, german (if available)
language_scope A hash of the language scope for the language including: name, code (if available)
language_type A hash of the language type for the language including: name, code (if available)
language_family A hash of the language family for the language including: name (if available)

Marketplace Glossaries

/marketplace-glossaries

TM-Town's Marketplace Glossaries API is an open endpoint where you can get a list of all of the terminology glossaries currently for sale on the TM-Town Terminology Marketplace.

Response
url A link to the glossary on the TM-Town Terminology Marketplace.
title The title of the glossary.
overview An overview of the contents of the glossary.
source_language The language of the source terms in the glossary.
target_language The language of the target terms in the glossary.
term_concept_count The number of term concepts in the glossary.
price The price of the glossary in Euros.
seller The seller's preferred name, or if blank the seller's TM-Town username.
seller_profile_url A link to the seller's TM-Town profile.
sales The number of sales of the glossary.
average_rating The average rating (if available) of the glossary (0 to 5 scale).
glossary_id The unique identifier of the glossary in TM-Town's system.

Nakōdo Search (URL)

/public-nakodo-searches

TM-Town's Nakōdo Search (URL) API (POST) is an open endpoint where you can search a text that needs to be translated and TM-Town will return a temporary URL where you can review the results of the relevant translators who have translated similar documents in the past.

All language parameters require the two character ISO 639-1 code be used.

Request Parameters
source_language
REQUIRED		 The language code of the source text
target_language
REQUIRED		 The language code of the desired translation
text
REQUIRED		 The text (or a sample of the text) that needs to be translated
Response
url A URL to review the Nakōdo. The URL link expires after 30 minutes.

Nakōdo Search (Data)

/nakodo-search-data-only

TM-Town's Nakōdo Search (Data) API (POST) is an open endpoint where you can search a text that needs to be translated and TM-Town will return information on relevant translators who have translated similar documents in the past.

All language parameters require the two character ISO 639-1 code be used.

Request Parameters
source_language
REQUIRED		 The language code of the source text.
target_language
REQUIRED		 The language code of the desired translation.
text
REQUIRED		 The text (or a sample of the text) that needs to be translated.
Response
results An array of translators sorted by similarity score.

API Key Endpoints

Job Message

/job-message

TM-Town's Job Message API (POST) is an API key endpoint where you can send a job message to a translator on TM-Town.

All language parameters require the two character ISO 639-1 code be used.

Request Parameters
username
REQUIRED		 The username of the TM-Town translator whom you would like to send a message to.
sender_name
REQUIRED		 The name of the sender of the message.
sender_email
REQUIRED		 The email address of the sender.
source_language
REQUIRED		 The language code of the source text.
target_language
REQUIRED		 The language code of the desired translation.
budget
REQUIRED		 A string containing either: 'low', 'medium', or 'high' depending on the sender's budget. 'low' is for Entry Level jobs of less than $0.09/word. 'medium' is for Intermediate jobs of $0.09/word - $0.15/word. 'high' is for Expert jobs of greater than $0.15/word.
message
REQUIRED		 The text of the message to send to the translator.
Response
message Message received. Thank you for your interest in TM-Town and the translators on this site.

OAuth2 Endpoints

Registering Your App

Before registering an application, please be sure to read the API Partners Terms of Service and Conditions of Use. By creating an OAuth2 application on TM-Town you are agreeing to these terms and any violations will result in your app immediately being removed.

Quick Start Steps:

  1. Register for a free TM-Town account.
  2. Register your app at TM-Town. You will be assigned a Client ID and a Client Secret.
  3. Find an OAuth2 client library in your language and configure it with your Client ID, Client Secret, and Redirect URI. Use https://www.tm-town.com/oauth/authorize to request authorization and https://www.tm-town.com/oauth/token to get access tokens.
  4. Make an authorized request to https://www.tm-town.com/api/user to test it out. See below for more information on how to make a request to this endpoint.

OAuth2 Playground

The following is an example of how to test out TM-Town's OAuth2 endpoints using Google's OAuth2 playground.

  1. Register for a free TM-Town account.
  2. Register your app at TM-Town. Use https://developers.google.com/oauthplayground as the Redirect URI. You will be assigned a Client ID and a Client Secret.
  3. Visit Google's OAuth2 Playground in your browser.
  4. Click on the settings in the top right corner (gear icon). Set the settings to the following:
    • OAuth flow: Server-side
    • OAuth endpoints: Custom
    • Authorization endpoint: https://www.tm-town.com/oauth/authorize
    • Token endpoint: https://www.tm-town.com/oauth/token
    • Access token location: access_token URL parameter
    • OAuth Client ID: the Client ID from the TM-Town app you registered
    • OAuth Client secret: the Client Secret from the TM-Town app you registered
  6. In the text field on the left, enter public for the scope and click Authorize APIs. It should bring you to TM-Town and load the authorization screen, and once you authorize the request, return you to the Google OAuth2 Playground.
  7. Click Exchange authorization code for tokens to receive a token (you'll need to do this within 30 seconds). The response on the right should show the access token.
  8. Set the Request URI on the left to https://www.tm-town.com/api/user and click Send the request. The response should contain data from your own TM-Town.com profile.

To use the TM-Town User Segments API in the Google OAuth2 Playground, you need to set the scope to read_tms in step 5. To use the TM-Town User Terms API in the Google OAuth2 Playground you need to set the scope to read_terms in step 5. In your own application, it is possible to request the user to authorize multiple scopes. This is done by appending each scope to the URL such as https://www.tm-town.com/oauth/authorize?client_id=your-client-id&redirect_uri=your-redirect-uri&response_type=code&scope=public+read_tms+read_terms.

OAuth2 Scopes

The following are the different scopes available for the TM-Town OAuth2 API:

Name Description
public Access your public data
read_documents Access metadata on any documents you have uploaded
read_terms Read your private terminology files
read_tms Read your private translation memory files (including any source or target documents you have uploaded)
write Upload and save new translation memory or terminology files to your account

User

/user

TM-Town's User API is an OAuth2 API where you can get detailed information on translators who have authorized your application.

The scope of this endpoint is public. An app with this scope will request the following permissions from the user:

Request Parameters
access_token
REQUIRED		 The OAuth2 access token you received for this translator
Response
id An ID uniquely identifying the translator's TM-Town account.
username The translator's TM-Town username
name The translator's name (if available)
preferred_name The translator's preferred name (if available)
country The translator's country (if available)
gender The translator's gender (if available)
fields_of_expertise An array of the translator's fields of expertise (if available)
language_pairs An array of language pairs. Each language pair is an array where the zero index value (zeroth element) is the source language and the last element (1 index) is the target language. (if available)
translation_units The number of translation units the translator has uploaded to TM-Town
term_concepts The number of term concepts the translator has uploaded to TM-Town
rank The translator's rank on TM-Town (rank is based on the number of translation units uploaded)
software An array of the software the translator uses / is familiar with (if available)
about 'About Me' for the translator

Segments

/user-segments

TM-Town's Segments API is an OAuth2 API where you can search a translator's translation memory files.

The scope of this endpoint is read_tms. An app with this scope will request the following permissions from the user:

All language parameters require the two character ISO 639-1 code be used.

Request Parameters
access_token
REQUIRED		 The OAuth2 access token you received for this translator
query
REQUIRED		 A query to search for a segment
tokens
OPTIONAL		 A comma separated list of document tokens to search (if this parameter is left blank the request which search all documents of the translator)
source_language
OPTIONAL		 The language of the source segment
target_language
OPTIONAL		 The language of the target segment
match_language
OPTIONAL		 Have either the source or target segment match a specific language
exact_match
OPTIONAL Default: false		 Perform a case-sensitive exact match search (options: true, false)
regex_search
OPTIONAL Default: false		 Perform a regular expression search. Note that the regular expression must match the entire string you are searching for (options: true, false)
Response
role The role of the segment: source or target
document_name The name of the document that the segment is associated with
document_token The token of the document that the segment is associated with
language The language of the segment (if available)
text The text of the segment
creation_date The creation date of the segment (if available)
word_count The word count of the segment (if available)

Terms

/user-terms

TM-Town's Terms API is an OAuth2 API where you can search a translator's terminology files.

The scope of this endpoint is read_terms. An app with this scope will request the following permissions from the user:

All language parameters require the two character ISO 639-1 code be used.

Request Parameters
access_token
REQUIRED		 The OAuth2 access token you received for this translator
query
REQUIRED		 A query to search for a term
tokens
OPTIONAL		 A comma separated list of document tokens to search (if this parameter is left blank the request which search all documents of the translator)
source_language
OPTIONAL		 The language of the source term
target_language
OPTIONAL		 The language of the target term
match_language
OPTIONAL		 Have either the source or target term match a specific language
exact_match
OPTIONAL Default: false		 Perform a case-sensitive exact match search (options: true, false)
regex_search
OPTIONAL Default: false		 Perform a regular expression search. Note that the regular expression must match the entire string you are searching for (options: true, false)
Response
term The term
role The role of the term - source or target
document_name The name of the document that the term is associated with
document_token The token of the document that the segment is associated with
language The language of the term
part_of_speech The part of speech of the term (if available)
normative_status The normative status of the term - preferred, admitted or deprecated (if available)
gender The gender of the term - masculine, feminine, neuter or not applicable (if available)
number The number of the term - singular, plural or not applicable (if available)

Documents

/documents

TM-Town's Documents API (GET) is an OAuth2 API where you can query a translator's uploaded documents.

The scope of this endpoint is read_documents. An app with this scope will request the following permissions from the user:

Request Parameters
access_token
REQUIRED		 The OAuth2 access token you received for this translator
file_type
OPTIONAL		 The type of document: tm_file, terminology_file, source_document or target_document (the default is all)
Response
name The name of the document
token A unique identifier for the document
file_extension The extension of the document
size The size of the document (in bytes)
file_type The type of document: tm_file, terminology_file, source_document or target_document
word_count The word count of the document (if available)
tu_count The number of translation units in the document (if available)
seg_count The number of segments in the document (if available)
tc_count The number of term concepts in the document (if available)
term_count The number of terms in the document (if available)
language The language of the document (available for monolingual documents)
language_pairs An array of language pairs. Each language pair is an array where the zero index value (zeroth element) is the source language and the last element (1 index) is the target language. (if available)
fields_of_expertise An array of the fields of expertise the document has been tagged with

Documents

/documents

TM-Town's Documents API (POST) is an OAuth2 API where you can upload a new document into a translator's TM-Town account.

The scope of this endpoint is write. An app with this scope will request the following permissions from the user:

Request Parameters
access_token
REQUIRED		 The OAuth2 access token you received for this translator
tag_list
REQUIRED		 A comma separated list of fields of expertise for the document (minimum of 1, maximum of 3)
file_type
REQUIRED		 The type of document: tm_file, terminology_file, source_document or target_document
new_document
OPTIONAL		 Set this to true if you would like to create a blank document which you will later add translation units to through the TM-Town Translation Units API: true, false
Response
name The name of the file
token A unique identifier for the file
file_extension The extension of the file
size The size of the file (in bytes)
file_type The type of document: tm_file, terminology_file, source_document or target_document

Glossary

/glossary

TM-Town's Glossary API (POST) is an OAuth2 API where you can upload a terminology glossary into a translator's TM-Town account.

The scope of this endpoint is write. An app with this scope will request the following permissions from the user:

Request Parameters
access_token
REQUIRED		 The OAuth2 access token you received for this translator
tag_list
REQUIRED		 A comma separated list of fields of expertise for the document (minimum of 1, maximum of 3)
title
REQUIRED		 The title of the glossary
source_language
REQUIRED		 The two character ISO 639-1 code or three character ISO 639-3 code of the source language of the glossary
target_language
REQUIRED		 The two character ISO 639-1 code or three character ISO 639-3 code of the target language of the glossary
source_terms
REQUIRED		 For each source term please format your request as follows:
target_terms[]=hello&source_terms[]=world
The number of source terms must match the number of target terms, definitions, fields and kudoz_ids.
target_terms
REQUIRED		 For each target term please format your request as follows:
target_terms[]=hola&target_terms[]=mundo
The number of target terms must match the number of source terms, definitions, fields and kudoz_ids.
definitions
OPTIONAL		 For each definition please format your request as follows:
definitions[]=greeting&definitions[]=earth
The number of definitions must match the number of source terms, target terms, fields and kudoz_ids.
fields
OPTIONAL		 For each field please format your request as follows:
fields[]=business,marketing&fields[]=geography
The number of fields must match the number of source terms, target terms, definitions and kudoz_ids. For each term concept you can supply a comma separated list of fields.
kudoz_ids
OPTIONAL		 For each KudoZ id please format your request as follows:
kudoz_ids[]=345443&kudoz_ids[]=322322
The number of kudoz_ids must match the number of source terms, target terms, definitions and fields.
profile_url
OPTIONAL		 The translator's public profile url on the sender's site.
glossary_id
OPTIONAL		 The id of the glossary on the sender's site.
Response
document_id The ID of the new glossary document in TM-Town's system.
user_id The ID of the translator in TM-Town's system.

Parallel Texts

/parallel-texts

TM-Town's Parallel Texts API (POST) is an OAuth2 API where you can upload a source text and a target text into a translator's TM-Town account. The documents will be automatically aligned and 3 documents will be saved in the translator's account: a source document, a target document and the aligned TM file.

The scope of this endpoint is write. An app with this scope will request the following permissions from the user:

All language parameters require the two character ISO 639-1 code be used.

Request Parameters
access_token
REQUIRED		 The OAuth2 access token you received for this translator
tag_list
REQUIRED		 A comma separated list of fields of expertise for the document (minimum of 1, maximum of 3)
source_language
REQUIRED		 The two character ISO 639-1 code of the source text
source_text
REQUIRED		 The text of the source document
target_language
REQUIRED		 The two character ISO 639-1 code of the target text
target_text
REQUIRED		 The text of the target document
profile_url
OPTIONAL		 The translator's public profile url on the sender's site.
sample_id
OPTIONAL		 The id of the source and target sample pair on the sender's site.
Response
source_document_id The ID of the source document in TM-Town's system.
target_document_id The ID of the target document in TM-Town's system.
aligned_document_id The ID of the aligned document in TM-Town's system.

Translation Units

/translation-units

TM-Town's Translation Units API (POST) is an OAuth2 API where you add a new translation unit to a document already in a translator's TM-Town account. The document must be a translation memory file (not a monolingual document).

The scope of this endpoint is write. An app with this scope will request the following permissions from the user:

All language parameters require the two character ISO 639-1 code be used.

Request Parameters
access_token
REQUIRED		 The OAuth2 access token you received for this translator
name
REQUIRED		 The name of the document you will be adding the translation unit to
token
OPTIONAL		 The token of the document you will be adding the translation unit to (required if there are multiple documents with the same name in that translator's account)
source_text
REQUIRED		 The text of the source segment of the new translation unit
source_language
REQUIRED		 The language code of the new source segment
target_text
REQUIRED		 The text of the target segment of the new translation unit
target_language
REQUIRED		 The language code of the new target segment
Response
name The name of the document the translation unit was added to
translation_units The new translation unit count of the updated document (excludes duplicates)
segments The new segment count of the updated document (excludes duplicates)
user_translation_units_count The new translation unit count of the translator (excludes duplicates)