Export (0) Print
Expand All
12 out of 15 rated this helpful - Rate this topic

Paraphrase API

The Paraphrase API is an English-to-English machine translation system that rephrases English sentences in English. This API uses the same architecture that the Microsoft Translator API uses for translation. The purpose of the Paraphrase API is to reword or rephrase the content without losing its meaning or idea. The Paraphrase API uses the REST service using GET over HTTP. It uses simple XML and JSON formatting.

Endpoint

The endpoint of the Paraphrase API is either one of the following:

  • http://api.microsofttranslator.com/v3/json/paraphrase
  • http://api.microsofttranslator.com/v3/rest/paraphrase
Parameters
Parameter Description
appId Required. A string containing the access token or application ID.
language Required. A string representing the language code. This parameter supports only ENGLISH with en as the language name.
Category Optional. A string containing the category or domain of the translation. This parameter supports only the default option general.
sentence Required. A sentence that you want to paraphrase. This parameter supports only one sentence as the input. Multiple sentences will fail, and an error code with the message will be displayed.
maxTranslations Optional. The number of paraphrased sentences for the sentence that you specified in the sentence parameter. The API will return as many paraphrased sentences as the number that you specify in the maxTranslations parameter.

Return value

The return value provides as many paraphrased sentences as the number specified in the maxTranslations request parameter.

JSON
ParaphraseResponse
{
     int errorCode;  // A positive number representing an error condition
     string errorMessage; // A descriptive error message 
     string[] paraphrases; // all paraphrases found
}

Error Messages

The following are the most common error messages.

  • ErrorNoParaphrasesFound – “The system did not find any paraphrase for the input sentence.”
  • ErrorInvalidAppid – “The AppId X is invalid.”
  • ErrorInvalidNumberOfSentences – “Only one sentence is supported. The request contains X sentences.”
  • ErrorInvalidCategory – “Category X is invalid.”
  • ErrorInvalidLanguage – “Language X is not supported.”

Example

C#
PHP

                                
using System;
using System.IO;
using System.Net;
using System.Runtime.Serialization;
using System.Runtime.Serialization.Json;
using System.Text;
using System.Web;
namespace MicrosoftTranslator.ParaphraseSample
{
    class Program
    {
        static void Main(string[] args)
        {
            AdmAccessToken admToken;

            string urlTemplate = "http://api.microsofttranslator.com/v3/json/paraphrase?sentence={0}&language={1}&category={2}&maxParaphrases={3}";
            string sentence = "rephrasing is a hard problem for the computer.";
            string headerValue;
            //Get Client Id and Client Secret from https://datamarket.azure.com/developer/applications/
            AdmAuthentication admAuth = new AdmAuthentication("clientId", "ClientSecret");
            try
            {
                admToken = admAuth.GetAccessToken();
                DateTime tokenReceived = DateTime.Now;
                // Create a header with the access_token property of the returned token
                headerValue = "Bearer " + admToken.access_token;
                if ((DateTime.Now - tokenReceived).TotalSeconds > 600)
                {
                    throw new Exception("Authentication token expired");
                }
                else
                {
                    string url = string.Format(urlTemplate, sentence, "en-us", "general", "6");
                    string paraphraseResult = GetParaphrases(url, headerValue);
                    string[] paraphrases = paraphraseResult.Substring(paraphraseResult.IndexOf("paraphrases")).Split(new char[] { ':' });

                    foreach (string paraphrase in paraphrases)
                    {
                        Console.WriteLine(paraphrase);
                    }


                }
            }

            catch (Exception ex)
            {

                Console.WriteLine(ex.Message);

            }
            Console.WriteLine("Press any key to continue...");
            Console.ReadKey(true);

        }

        private static string GetParaphrases(string url, string headerValue)
        {
            string responseContent = string.Empty;

            using (HttpWebResponse webResponse = InvokeRestGetService(url, headerValue, null))
            {
                //extract response string from response and do further validations
                using (StreamReader streamResponse = new StreamReader(webResponse.GetResponseStream()))
                {
                    responseContent = streamResponse.ReadToEnd();
                }
            }

            return responseContent;
        }

        private static HttpWebResponse InvokeRestGetService(string url, string headerValue, IWebProxy proxy)
        {
            // build HTTP request
            HttpWebRequest restWebRequest = null;

            restWebRequest = (HttpWebRequest)WebRequest.Create(url);
            restWebRequest.Headers.Add("Authorization", headerValue);
            // If we have a proxy set it to avoid 503s
            if (proxy != null)
            {
                restWebRequest.Proxy = proxy;
            }
            restWebRequest.Method = "GET";

            // return HttpWebResponse
            return (HttpWebResponse)restWebRequest.GetResponse();
        }
    }
    [DataContract]
    public class AdmAccessToken
    {
        [DataMember]
        public string access_token { get; set; }
        [DataMember]
        public string token_type { get; set; }
        [DataMember]
        public string expires_in { get; set; }
        [DataMember]
        public string scope { get; set; }
    }

    public class AdmAuthentication
    {
        public static readonly string DatamarketAccessUri = "https://datamarket.accesscontrol.windows.net/v2/OAuth2-13";
        private string clientId;
        private string cientSecret;
        private string request;

        public AdmAuthentication(string clientId, string clientSecret)
        {
            this.clientId = clientId;
            this.cientSecret = clientSecret;
            //If clientid or client secret has special characters, encode before sending request
            this.request = string.Format("grant_type=client_credentials&client_id={0}&client_secret={1}&scope=http://api.microsofttranslator.com", HttpUtility.UrlEncode(clientId), HttpUtility.UrlEncode(clientSecret));
        }

        public AdmAccessToken GetAccessToken()
        {
            return HttpPost(DatamarketAccessUri, this.request);
        }

        private AdmAccessToken HttpPost(string DatamarketAccessUri, string requestDetails)
        {
            //Prepare OAuth request 
            WebRequest webRequest = WebRequest.Create(DatamarketAccessUri);
            webRequest.ContentType = "application/x-www-form-urlencoded";
            webRequest.Method = "POST";
            byte[] bytes = Encoding.ASCII.GetBytes(requestDetails);
            webRequest.ContentLength = bytes.Length;
            using (Stream outputStream = webRequest.GetRequestStream())
            {
                outputStream.Write(bytes, 0, bytes.Length);
            }
            using (WebResponse webResponse = webRequest.GetResponse())
            {
                DataContractJsonSerializer serializer = new DataContractJsonSerializer(typeof(AdmAccessToken));
                //Get deserialized object from JSON stream
                AdmAccessToken token = (AdmAccessToken)serializer.ReadObject(webResponse.GetResponseStream());
                return token;
            }
        }
    }
}

                                            
                                            

Goto Top

                                
<?php

class AccessTokenAuthentication {
    /*
     * Get the access token.
     *
     * @param string $grantType    Grant type.
     * @param string $scopeUrl     Application Scope URL.
     * @param string $clientID     Application client ID.
     * @param string $clientSecret Application client ID.
     * @param string $authUrl      Oauth Url.
     *
     * @return string.
     */
    function getTokens($grantType, $scopeUrl, $clientID, $clientSecret, $authUrl){
        try {
            //Initialize the Curl Session.
            $ch = curl_init();
            //Create the request Array.
            $paramArr = array (
                 'grant_type'    => $grantType,
                 'scope'         => $scopeUrl,
                 'client_id'     => $clientID,
                 'client_secret' => $clientSecret
            );
            //Create an Http Query.//
            $paramArr = http_build_query($paramArr);
            //Set the Curl URL.
            curl_setopt($ch, CURLOPT_URL, $authUrl);
            //Set HTTP POST Request.
            curl_setopt($ch, CURLOPT_POST, TRUE);
            //Set data to POST in HTTP "POST" Operation.
            curl_setopt($ch, CURLOPT_POSTFIELDS, $paramArr);
            //CURLOPT_RETURNTRANSFER- TRUE to return the transfer as a string of the return value of curl_exec().
            curl_setopt ($ch, CURLOPT_RETURNTRANSFER, TRUE);
            //CURLOPT_SSL_VERIFYPEER- Set FALSE to stop cURL from verifying the peer's certificate.
            curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);
            //Execute the  cURL session.
            $strResponse = curl_exec($ch);
            //Get the Error Code returned by Curl.
            $curlErrno = curl_errno($ch);
            if($curlErrno){
                $curlError = curl_error($ch);
                throw new Exception($curlError);
            }
            //Close the Curl Session.
            curl_close($ch);
            //Decode the returned JSON string.
            $objResponse = json_decode($strResponse);
            if ($objResponse->error){
                throw new Exception($objResponse->error_description);
            }
            return $objResponse->access_token;
        } catch (Exception $e) {
            echo "Exception-".$e->getMessage();
        }
    }
}

/*
 * Class:HTTPTranslator
 *
 * Processing the translator request.
 */
Class HTTPTranslator {
    /*
     * Create and execute the HTTP CURL request.
     *
     * @param string $url        HTTP Url.
     * @param string $authHeader Authorization Header string.
     *
     * @return string.
     *
     */
    function curlRequest($url, $authHeader){
        //Initialize the Curl Session.
        $ch = curl_init();
        //Set the Curl url.
        curl_setopt ($ch, CURLOPT_URL, $url);
        //Set the HTTP HEADER Fields.
        curl_setopt ($ch, CURLOPT_HTTPHEADER, array($authHeader));
        //CURLOPT_RETURNTRANSFER- TRUE to return the transfer as a string of the return value of curl_exec().
        curl_setopt ($ch, CURLOPT_RETURNTRANSFER, TRUE);
        //CURLOPT_SSL_VERIFYPEER- Set FALSE to stop cURL from verifying the peer's certificate.
        curl_setopt ($ch, CURLOPT_SSL_VERIFYPEER, False);
        //Execute the  cURL session.
        $curlResponse = curl_exec($ch);
        //Get the Error Code returned by Curl.
        $curlErrno = curl_errno($ch);
        if ($curlErrno) {
            $curlError = curl_error($ch);
            throw new Exception($curlError);
        }
        //Close a cURL session.
        curl_close($ch);
        return $curlResponse;
    }
}

try {
    //Client ID of the application.
    $clientID       = "clientId";
    //Client Secret key of the application.
    $clientSecret = "ClientSecret";
    //OAuth Url.
    $authUrl      = "https://datamarket.accesscontrol.windows.net/v2/OAuth2-13/";
    //Application Scope Url
    $scopeUrl     = "http://api.microsofttranslator.com";
    //Application grant type
    $grantType    = "client_credentials";

    //Create the AccessTokenAuthentication object.
    $authObj      = new AccessTokenAuthentication();
    //Get the Access token.
    $accessToken  = $authObj->getTokens($grantType, $scopeUrl, $clientID, $clientSecret, $authUrl);
    //Create the authorization Header string.
    $authHeader = "Authorization: Bearer ". $accessToken;

    //Set the params.
    $sentence      = "rephrasing is a hard problem for the computer.";
    $language      = "en-us";
    $category        = "general";
    $maxParaphrase = '6';
    
    $params = "sentence=".urlencode($sentence)."&language=$language&category=$category&maxParaphrases=$maxParaphrase";
    
    //HTTP paraphrase URL.
    $paraphraseUrl = "http://api.microsofttranslator.com/v3/json/paraphrase?$params";
    
    //Create the Translator Object.
    $translatorObj = new HTTPTranslator();
    
    //Call the curlRequest.
    echo $curlResponse = $translatorObj->curlRequest($paraphraseUrl, $authHeader);
    
} catch (Exception $e) {
    echo "Exception: " . $e->getMessage() . PHP_EOL;
}

/*
 * Create and execute the HTTP CURL request.
 *
 * @param string $url        HTTP Url.
 * @param string $authHeader Authorization Header string.
 * @param string $postData   Data to post.
 *
 * @return string.
 *
 */
function curlRequest($url, $authHeader) {
    //Initialize the Curl Session.
    $ch = curl_init();
    //Set the Curl url.
    curl_setopt ($ch, CURLOPT_URL, $url);
    //Set the HTTP HEADER Fields.
    curl_setopt ($ch, CURLOPT_HTTPHEADER, array($authHeader,"Content-Type: text/xml"));
    //CURLOPT_RETURNTRANSFER- TRUE to return the transfer as a string of the return value of curl_exec().
    curl_setopt ($ch, CURLOPT_RETURNTRANSFER, TRUE);
    //CURLOPT_SSL_VERIFYPEER- Set FALSE to stop cURL from verifying the peer's certificate.
    curl_setopt ($ch, CURLOPT_SSL_VERIFYPEER, False);
    //Execute the  cURL session.
    $curlResponse = curl_exec($ch);
    //Get the Error Code returned by Curl.
    $curlErrno = curl_errno($ch);
    if ($curlErrno) {
        $curlError = curl_error($ch);
        throw new Exception($curlError);
    }
    //Close a cURL session.
    curl_close($ch);
    return $curlResponse;
}
                                            
                                            
Goto Top
Show:
© 2014 Microsoft. All rights reserved.