API Code examples


In order to facilitate the use of the STREAM API, we provide some pratical code examples of how to use the methods of the API. Before exploring this page, we advice you to first check our Quick Start page and our Documentation page.

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

Overview

If you followed the initial steps in our Quick Start page, feel free to jump over this overview. If you don't already have an API Key, please follow the instructions on the Quick Start page or the Documentation page.

For the examples, we consider the use of the Microsoft .NET Framework 3.5 and the C# language. However, the code logic and the use of the API services can be extrapolated to other languages and technologies. We also assume you were able to create a service reference to the API Web Services. For more information, please view the Documentation page.

A simple HelloWorld

If you have already experimented the
Hello World section in our Quick Start page , feel free to skip ahead.

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.

Using Authentication

If you have already experimented the
Consuming services that require authentication section in our Quick Start page , feel free to skip ahead.

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 a 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 languages and specialities

Several methods of the STREAM API use language and specialism as an input parameter, in the form of an numerical ID, . Therefore, the API contains some methods that allow you to obtain the complete list of available languages and specialities, with their ID's.

The API provides the following methods:
GetLanguagesList , GetSpecialitiesList, GetAvailableSpecialities and GetAvailableTargetLanguages. You can learn more about each of these functions on the Documentation page.
These methods can be used without authentication.

Obtaining a list of supported languages

To obtain a list of suported languages, use the method GetLanguagesList . The code below is an example of how 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.

Obtaining a list of supported specialities

To obtain a list of suported specialities, use the method GetSpecialitiesList . The code below is an example of how to call this method.
...
try
{
    //call the GetSpecialitiesList method. This method returns an array of SOAPSpeciality objects, which 
    //represent a speciality in the STREAM system
    SOAPspeciality[] specs = YourServiceReference.GetSpecialitiesList();

    //display the obtained languages in the Output window
    foreach (SOAPspeciality spec in specs)
        System.Diagnostics.Debug.WriteLine(spec.specialityID + " - " + spec.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 specialities. You can learn more about the GetSpecialitiesList method in our Documentation page.

Obtaining a language ID

Some of the methods provided by the API accept languages parameters, in the form of a numeric ID. The language ID must one the possible values of the Languages code list .

To facilitate this task, we provide the GetLanguageID method, that will allow you to get the language ID by specifying the language name.

...
try
{
    string languageName = "English"; //just as an example
    
    //call the GetLanguageID method. This method returns a SOAPLanguage object
    SOAPlanguage language = YourServiceReference.GetLanguageID(languageName);

    //display the obtained languages ID the Output window
    System.Diagnostics.Debug.WriteLine(language.languageID);
}
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 find the language ID in the languageID member of the SOAPlanguage object. If the value of this member is -1, it means that it did not find the language. When no langauge is found, please verify that you specified a correct language and that it is contained in the Languages code list .

Obtaining a language ID using a RFC 5646 language code

For a more formal specification, we can obtain language ID's using the language RFC 5646 code. This can be done by using the GetLanguageIdRfc5646 method.

...
try
{
    string languageCode = "pt-BR"; //just as an example
    
    //call the GetLanguageIdRfc5646 method. This method returns a SOAPLanguage object
    SOAPlanguage language = YourServiceReference.GetLanguageIdRfc5646(languageCode);

    //display the obtained languages ID the Output window
    System.Diagnostics.Debug.WriteLine(language.languageID);
}
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 find the language ID in the languageID member of the SOAPlanguage object. If the value of this member is -1, it means that it did not find the language.

Obtaining a list of available specialities

The available specialities depend on the source language. To obtain a list of available specialities for a specific language, use the method GetAvailableSpecialities . The code below is an example of how to call this method.
...
try
{
    //get the language ID for the source language
    int languageSourceID = ((SOAPlanguage) YourServiceReference.GetLanguageID("English")).languageID;

    //call the GetAvailableSpecialities method. This method returns an array of SOAPSpeciality objects, which 
    //represent a speciality in the STREAM system
    SOAPspeciality[] specs = YourServiceReference.GetAvailableSpecialities(languageSourceID);

    //display the available specialities in the Output window
    foreach (SOAPspeciality spec in specs)
        System.Diagnostics.Debug.WriteLine(spec.specialityID + " - " + spec.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 specialities. You can learn more about the GetAvailableSpecialities method in our Documentation page.

Obtaining a list of available target languages

The available target languages refers to the language you wish to translate to. Their availability depends on the source language and a speciality. To obtain a list of available target languages for a specific language and speciality, use the method GetAvailableTargetLanguages . The code below is an example of how to call this method.
...
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)

    //call the GetTargetLanguages method. This method returns an array of SOAPSpeciality objects, which 
    //represent a speciality in the STREAM system
    SOAPlanguage[] languages = YourServiceReference.GetAvailableTargetLanguages(languageSourceID, specialityID);

    //display the available specialities in the Output window
    foreach (SOAPlanguage lang in languages)
        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 specialities. You can learn more about the GetAvailableSpecialities method in our Documentation page.

Obtaining quotes

In order to order a translation using the STREAM API you need to obtain a quote. The STREAM API contains several functions to obtain a quote for a 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.

Obtaining a quote

One of the most simple quotation methods is the
GetQuoteForPlainText. This method allows you to pass a piece of text to be quoted. The code below is an example of how to call this method.
...
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);
}
...

The function returns a SOAPresponse object. If no error occurs, the m_quotes member will contain an array with the quotes. If an error ocurred, the errorPresent property in the m_errors member will be true, as can be seen in the example. You can learn more about the GetQuoteForPlainText method in our Documentation page.

Requesting a translation

After obtaining the quotation for a translation service, you can order the translation. This step, in its simplest form, consists basically in calling the CreateOrder method, passing the ID of the quote that you desire.

Create an order

Let's use the
CreateOrder method to order a translation, based in a quote ID.
...
try
{
    //this is just an example
    int selectedQuote = 65401; 
    
    SOAPresponse response = YourServiceReference.CreateOrder(AuthToken, selectedQuote);

    //check if there was an error during the ordering process
    if (response.m_errors.errorPresent == true)
    {
        System.Diagnostics.Debug.WriteLine(response.m_errors.errorCode + response.m_errors.description);
    }
    else
    {
        System.Diagnostics.Debug.WriteLine("Ordered with success");
    }
}
catch (Exception ex)
{
    //if an error occurs, display the error message in the Output window
    System.Diagnostics.Debug.WriteLine(ex.Message);
}
...

The function returns a SOAPresponse object. If no error occurs, the m_quotes member will contain an array with the quotes. If an error ocurred, the errorPresent property in the m_errors member will be true, as can be seen in the example. You can learn more about the GetQuoteForPlainText method in our Documentation page.