API Quick Start

This Quick Start guide allows you to quickly get started with TranslateMedia STREAM API. You can follow these steps to start testing the API and learn how to use it and integrate it with your system. You can also check our Documentation page to learn more about the API and all ther services we provide.

Please use the side menu to navigate through the quick start guide. If you need help or some other form of support, please contact us .

Overview

The best way to get started with the STREAM API is to obtain an API Key and start experimenting the API, using our Sandbox testing envirnoment. To obtain an API Key, you will need to
login and go to the API Key Management page. If you are not yet registered with TranslateMedia, please register yourself.

Your API Key should look similiar to the example below. Please note that your API Key must be kept private.


pkcB5/I(Upm$4Wy=PtFkSic1X^I!uBQ7V>+@9cq$gt5;Sx:w(a;t.J9M@r$Urm3!


In order to initially test our API, we provide a Sandbox endpoint, which serves as a testing environment. Before using the live API, we strongly suggest that you start by testing your code against the Sandbox environment. When you want to start using the live endpoint, you can find the endpoint address in our Documention page.

The STREAM API is implemented as a SOAP based Web Service. You can find the STREAM API Sandbox services at:


The WSDL is located at:




Create a proxy client that will allow you to comunicate to the STREAM API Web Services. If you use Microsoft .NET or Java development technologies, your IDE should allow you to quickly create a proxy client just by specifying the address of the WSDL, automatically generating the service reference and the necessary classes.

The following examples use Microsoft .NET Framework 3.5 and the C# language. However, the code logic and the use of the API services extend to other languages and technologies.

The examples assume that you were able to create a service reference to the STREAM API Web Services.

Hello World

To test the connection to the STREAM API, let's call the
HelloWorld service. This service exists only for connection testing purposes.

...
try
{
    //call the HelloWorld method
    string resultMessage = YourServiceReference.HelloWorld();

    //display the result message in the Output window
    System.Diagnostics.Debug.WriteLine(resultMessage);
}
catch (Exception ex)
{
    //if an error occurs, display the error message in the Output window
    System.Diagnostics.Debug.WriteLine(ex.Message);
}
...

If you are successful, you will receive the following message: "Hello World - You are connected to TranslateMedia." If your code is correct and you obtain an error while trying to connect, please make sure your internet connection is working.


Consuming some simple services

Some of the services that the STREAM API provides do not need authentication. For example, the
GetLanguagesList method allows you to obtain a list of all the supported languages. Let's try to call this method.

...
try
{
    //call the GetLanguagesList method. This method returns an array of SOAPLanguage objects, which 
    //represents a language in the STREAM system
    SOAPlanguage[] langs = YourServiceReference.GetLanguagesList();

    //display the obtained languages in the Output window
    foreach (SOAPlanguage lang in langs)
        System.Diagnostics.Debug.WriteLine(lang.languageID + " - " + lang.description);                
}
catch (Exception ex)
{
    //if an error occurs, display the error message in the Output window
    System.Diagnostics.Debug.WriteLine(ex.Message);
}
...

If you are successful, you will obtain a list of languages. You can learn more about the GetLanguagesList method in our Documentation page.


Consuming services that require authentication

Some services require you to authenticate yourself. To test the authentication let's call the
HelloWorldWithAuthentication method. This method exists only for testing purposes.

To provide a secure use of our API, we use a Token based authentication. You will need to authenticate yourself using your account username and API Key. Upon a sucessful authentication, the API will generate and return an Authentication Token that you will use to make all posterior service calls. This Authentication Token has an activity expiration time, in a similar way to a session token.

...
//set up a Authentication Header with you authentication credentials
AuthenticationHeader credentials = new AuthenticationHeader();
credentials.Username = "YourUsername";
credentials.ApiKey = "YourPrivateApiKey";

try
{
     //authenticate and obtain the Authentication Token
     AuthenticationToken AuthToken = YourServiceReference.Authenticate(credentials);

     if (AuthToken.authenticationSuccessful)
     {
         //call the HelloWorlWithAuthentication method, passing the Authentication Token
         string resultMessage = YourServiceReference.HelloWorldWithAuthentication(AuthToken);

         //display the result message in the Output window
         System.Diagnostics.Debug.WriteLine(resultMessage);
     }
     else
     {
         //if the authentication is not successful, display the returned error message in the Output window
         System.Diagnostics.Debug.WriteLine(AuthToken.m_errors.description);
     }
}
catch (Exception ex)
{
     //if an error occurs, display the error message in the Output window
     System.Diagnostics.Debug.WriteLine(ex.Message);
}
...


To authenticate and obtain an Authentication Token, you must call the Authenticate method, providing your authentication credentials. If the authentication fails, you will receive an error description message that will allow you to know why the authentication failed. You can learn more about the Authenticate method and possible error messages in the Documentation page.

If your call to the HelloWorldWithAuthentication method is successful, you will receive the message: "Hello World - You are authenticated and connected to TranslateMedia.".


Obtaining a quote for a translation

The STREAM API contains several functions to obtain a quote for the translation service, based on input parameters like: source and target languages, speciality, plain text or several other formats of source document, authenticity certification and some others advanced user settings.

Let's use the GetQuoteForPlainText to obtain a quote for a text translation.

...
try
{
    //get the language ID for the source language
    int languageSourceID = ((SOAPlanguage)YourServiceReference.GetLanguageID("English")).languageID;
    int specialityID = 16; // General (consult the specialities code list)

    //to keep the example simple, we are not checking if this is a available target language considering
    //the source language and the speciality
    int[] languageTargetID = { ((SOAPlanguage)YourServiceReference.GetLanguageID("French")).languageID };

    //the plain text to translate
    string plainText = "The quick brown fox jumps over the lazy dog";

    //call the GetQuoteForPlainText method. This method returns a SOAPreponse object
    SOAPresponse response = (SOAPresponse)YourServiceReference.GetQuoteForPlainText(AuthToken, 
    languageSourceID, specialityID, languageTargetID, plainText);

    //check if there was an error during the quote calculation process
    if (response.m_errors.errorPresent == true)
    {
        System.Diagnostics.Debug.WriteLine(response.m_errors.errorCode + response.m_errors.description);
    }
    else
    {
        //display the quotes in the Output window
        foreach (SOAPquote quote in response.m_quotes)
        {
            System.Diagnostics.Debug.WriteLine("Quote ID: " + quote.idQuote + 
            "Quote price: " + quote.dQuotePrice + quote.sCurrency + 
            " Estimate: " + quote.dtTargetCompletion + " type? " 
            + quote.byType + " Execution type(min): " 
            + quote.iMinutesElapsed);
        }
    }

}
catch (Exception ex)
{
    //if an error occurs, display the error message in the Output window
    System.Diagnostics.Debug.WriteLine(ex.Message);
}
...


If you are successful you will obtains the quotes for the translation of the text. You can learn more about the GetQuoteForPlainText method in our Documentation page.


What's next ?

After reading and trying our Quick Start, check our
Documentation page to learn more about the STREAM API and each of our methods. You can also check our Examples page for pratical examples of how to use some of the API methods. If you need any additional help, please contact us .