The AppID

Before you can use any of the Bing APIs you have to get an AppID - which is used to identify you as you make API calls. To get an AppID you have to have to visit the Bing Developer Center and log in with a Windows Live ID.  You then have to provide some information - and email address, name of your app, url of your website etc.

Don't worry too much about the name of your app the sign up is automatic and you can request another AppID when you decide to move to a real project. When you select the check box to agree to the terms and click Agree you get a long string of hex digits that identify your use of the API.

The terms that you are agreeing to seem fairly reasonable and straightforward. Basically you agree not to do anything illegal or to misrepresent things. This basically means that if you mix the Microsoft data with other data you have to make sure it is clear where each comes from. The key restriction is that you can't make more than 7 queries per second per IP address. If you do need to make more then you need to contact Microsoft and discuss it.

You might not like being regulated in this way but this is a free service.

Hola Mundo

Now you have an AppID you can get started with the translate API using the JSONP version of the API.

All you have to do is setup a dynamic script object using the DOM, set some parameters in the script URL and provide a callback function to process the result.

You can see all of the methods that you can call using the API documentation. For the example lets use the Translate method - its simple and useful.

The URL for all of the Ajax methods is:

http://api.microsofttranslator.com/V2/Ajax.svc/

and next comes the name of the method - Translate in this case and then a query string of parameters:

• appId - your application Id
• oncomplete - the name of the callback function
• from - source language
• to - destination language
• text - text to be translated

Notice that you have to pass the name of the callback function and not the function itself. This distinction is often a problem when functions have to be specified - which to pass the name of the function or a reference to the function object. In this case it has to be the name of the function as a string.

To try this out let's start building a Translation object which has all of the data and methods needed. We can make this object a singleton because there is no particular need to create other copies of the object. This means we can define it as an object literal

var Translate={
 baseUrl:"http://api.
  microsofttranslator.com/V2/Ajax.svc/";
 appId:"a long string of hex digits",

The baseUrl and appid are the only two properties of the object.

In this case the only method is translate but you can add additional methods - one for each of the translate API methods.

The translate methods starts off by creating a script object:

translate:function(text,from,to,callback){
 var s = document.createElement("script");

Next we build up the src URL one parameter at a time for clarity:

s.src =this.baseUrl+"/Translate";
s.src +="?oncomplete="+callback;
s.src +="&appId="+this.appId;
s.src +="&from" + from ;
s.src += "&to=" + to ;
s.src += "&text=" + text;

Now that we have the URL we can add the dynamic script to the DOM:

  document.getElementsByTagName(
               "head")[0].appendChild(s);
 }
}

and this finished the object definition.

Now in the main program we need to define a callback:

var mycallback=function(result){
                        alert(result)};

and call the translate method:

Translate.translate("Hello World","en",
                      "es","mycallback");

The result is that Hello World is translated to Hola Mundo and displayed in an alert box.Once again notice that the callback function is specified as a string giving the name of the function to use.

What you do next is up to you but adding additional methods to the Translate object is a good way to proceed.

The complete listing is:

<script type="text/javascript"> 
 var Translate={
  baseUrl:"http://api.
    microsofttranslator.com/V2/Ajax.svc/",
  appId:"hex digits",
  translate:function(text,from,to,
                              callback){
   var s = document.createElement("script");
   s.src =this.baseUrl+"/Translate";
   s.src +="?oncomplete="+callback; 
   s.src +="&appId="+this.appId;
   s.src +="&from" + from ;
   s.src += "&to=" + to ;
   s.src += "&text=" + text; 
   document.getElementsByTagName(
              "head")[0].appendChild(s);
  }
 }
 var mycallback=function(result){
                         alert(result)};
 Translate.translate("Hello World",
               "en","es","mycallback");
</script>

If you would like the code for this project then register and click on CodeBin.

If you would like to be informed about new articles on I Programmer you can either follow us on Twitter, on Facebook  or you can subscribe to our weekly newsletter.