Getting Images from Live Search API

I couldn’t believe it, it was the forth straight snow day !
Actually, it was getting really nasty out there, with drivers spinning on icy roads and bumping into each others’ car and subzero temperatures. Better stay inside, for sure!
I would not feel guilty to dedicate a bit more time to keep developing the Image Slide control for getting images from Live Search through its APIs, described in part 1 of this blog series.

Query and ImageQuery Classes

As you probably read in part 2, I had left my work thinking about how to facilitate the creation of Microsoft Live Search queries. What I wanted to develop was a component that would help me reduce the chances of making errors while using the various operators.

I started up defining few enumerations for names and codes of Countries and Languages.
  It would definitely help me reduce spelling errors. Well, I am sure that is only my problem and you all know how to consistently spell Latvian and/or Lithuanian in your code.
  At the same time, it would avoid the need to look up for cryptic codes. Again, I should know better, and always remember that "zh_chs","zh_cht" are code names for Simplified Chinese and Traditional Chinese.

With these types defined, I could extend my Query wrapper object, adding a couple of collections to store the list of Countries and Languages that I wanted to include in my queries.

I needed another couple of collections for the list of Sites that should be included and/or excluded from the queries.
  These two properties can be very interesting if you want to make sure that the query results are coming from content in specific sites, or they avoid other sites. Call it human relevance boost! :-)

What else did I need?
Oh, sure! Live Search API allows to specify the aspect ratio, the type of images, size and subjects. These are all string filters that can be added to the query.
  I could definitely use other enumerations here.  And, I could then add a few properties to my Query object to refer to the instances.

But, wait! Hold on… not so fast…
The Live Search Web Service Application Programming Interface (API) Version 2.0 enables developers to build applications that can retrieve different types of information from the Internet, supporting different types of information, including: Web, Images, News, Instant Answers, Ads, Related Search, Spell, Phonebook. (You can look up the documentation on MSDN).

So, really, these image related properties would be good for image oriented queries but not, let’s say, for News or Web ones.
  Well, I could always move these properties in a subclass of the Query object, say ImageQuery, couldn’t I?

Actually, now that I thought of it, the MaxNumOfImages properties that I had previously defined in the Query object could be in the ImageQuery as well. Or should I change its semantics and generalized it to make it become the MaxNumOfResults?
  Well, I thought the former would work better for my purpose, as I would make it easier for me to develop the web control and its design time support code.

Having said that, I was almost done…
In fact, I was left with reviewing serialization and de-serialization for the ImageQuery class, and then with creating a method that would output a well formed Live Search query, transforming the strongly typed property values in those strings that I had hard time manually composing and spelling.
  Additionally, I needed a helper method that would create a Live Search SearchRequest starting from the content of the ImageQuery, I called it LiveSearchExpression.

Finally, I could use the ImageQuery object to create a well formed Live Search API SearchRequest object, using the BuildRequest method, whose code is shown below.

public SearchRequest BuildRequest(String myAppId, 
                                  uint nImageOffset, 
                                  AdultOption myAdultOption)
{
    SearchRequest request = new SearchRequest();
    request.AppId = myAppId;
    request.Sources = new SourceType[] { SourceType.Image };
    request.Image = new ImageRequest();
    // Image-specific request fields (optional) 
    request.Image.Count = 50; // Always ask for maximum
    request.Image.CountSpecified = true;

    // Get images starting from a certain offset;
    request.Image.Offset = nImageOffset; 
    request.Image.OffsetSpecified = true;
    // Common request fields (required)  
    // Get Well Formed Query Text from this obiect       
    request.Query = LiveSearchExpression();
    // Common request fields (optional)
    [...]
    return request;
}

A coffee and a breakfast later, I was done with all that.
  And, I hope the class diagram below will help you have a better sense of it.

 Using Query/ImageQuery Classes

Now, I had no trouble in  processing queries that I would send to Live Search invoking its APIs, neither within the web control nor inside the web service that was actually calling Microsoft Live Search.

For example, within the code-behind the user control, I could write snippets like the following, where Query was the control property storing the query text, and the SlideShowExtender was the name of the homonym Ajax control used at runtime to invoke the web services, passing the ContextKey as its parameter.

if (!string.IsNullOrEmpty(Query))
{
            ImageQuery myIQ = new ImageQuery();
            myIQ.Text = Query;
            myIQ.IncludedCountries.Add(Countries.United_States);
            myIQ.ImageColor = ImageQuery.ImageColors.Color;
            myIQ.ImageSize = ImageQuery.ImageSizes.Medium;
            myIQ.ImageType = ImageQuery.ImageTypes.Photo;
            myIQ.ImageSubject = ImageQuery.ImageSubjects.NonPortrait;
            myIQ.MaxNumOfImages = 100;

            this.SlideShowExtender.ContextKey = myIQ.ToJSON();                                      
 }

Processing the query in the web service was also a breeze.

// Deserialize the ImageQuery from the passed parameter
ImageQuery myImgQuery = ImageQuery.CreateFromJSON(contextKey);

[…]

//Build the request for the right query at the right offset
SearchRequest request = myImgQuery.BuildRequest(m_LiveSearchAppId, 
                                                nOffset, 
                                                AdultOption.Moderate);

You know? Using Live Searh API was much easier than before. 

It was almost fun! :-) 

My end to end scenario was still working fine, my second coffee was long gone. It was definitely time for another one and a break.

Yes, I needed some fresh energy before tackling the development of the full blown web control, especially the design time support part… :-)

Don’t you love implementing design time support for web controls?
Well, I will tell you more on the next part… I guess.

Getting Images from Live Search API

So, if you read part I of this post, by now you should have an idea of the type of experience and components that I aimed to develop…
a web server rendering a client page with inside a custom control used to show and animate images found on Microsoft Live Search by invoking a web service running on web server…
Wow, that was mouthful! :-)

I hope the following diagram will help you navigate this architecture and have a feeling for the interactions among components… some details will follow

Ok, let’s get it started…

Sketching out the Web Control

I wasn’t sure exactly how the control would look like, so I decided to sketch it using a user control (.ascx) instead of starting with a full blown web control. That way I was able to experiment with the UX while figuring out the properties I needed for the control to support my user experience, and I would not have to work on the design time support until the control design was hardened…

Creating the first instance of the control was a piece of cake.
After all, I needed just a label for the image Title, an Image for the picture, a label for the image Description (which I decided to use to show the images’ source), and the Play/Stop, Next, Prev buttons to control the slide show. Pretty much something like this…

<asp:Panel ID="PD_SearchImagesSlideShow" runat="server" CssClass="searchimages_pd_slideshow">
            <asp:Panel ID="PD_Photo" CssClass="searchimages_pd_photo">
                <asp:Panel ID="PD_Title" CssClass="searchimages_pd_title" runat="server">
                    <asp:Label ID="lblImageTitle" runat="server"   />
                </asp:Panel>                                          
                <asp:Image  ID="myImage"  runat="server" CssClass="searchimages_pd_image" />                             
                <asp:Panel ID="PD_Desc" CssClass="searchimages_pd_desc" runat="server">
                    <asp:Label ID="lblImageDescription" runat="server"  />
                </asp:Panel> 
            </asp:Panel>
            <asp:Panel ID="PD_Btns"  runat="server" CssClass="searchimages_pd_btns">           
                <asp:Button ID="Btn_Previous" runat="server" Text="Previous"  />
                <asp:Button ID="Btn_Play" runat="server" Text="Play"/>
                <asp:Button ID="Btn_Next" runat="server" Text="Next"/>              
            </asp:Panel>
</asp:Panel>    

Oh, I almost forgot, the controls needed also an Ajax SlideShow extender, which comes with the Microsoft Ajax Control Toolkit. That would make the trick of requesting the images from my web service and animating them in a slide show on the client. If you are not familiar with extenders, think of them as Javascript that is associated with server controls (once they are instantiated in a web page) and used to extend (i.e. improve, aka make cool) their functionalities.

<ACT:SlideShowExtender ID="SlideShowExtender" AutoPlay="true" Loop="true"
                 ImageTitleLabelID="lblImageTitle"
                 TargetControlID="myImage"                                    
                 ImageDescriptionLabelID="lblImageDescription"  
                 PreviousButtonID="Btn_Previous"
                 PlayButtonID="Btn_Play" PlayButtonText="Play"  StopButtonText="Stop"
                 NextButtonID="Btn_Next"                                    
                 SlideShowServicePath="~/services/..." SlideShowServiceMethod="SearchPhotos"  
                 UseContextKey="true"
                 runat="server">                                   
</ACT:SlideShowExtender> 

For example (see snippet above), in the case of the SlideShow extender, you associate that to (at least) an image and – at runtime - the extender will fetch images from a web service and replace the content of the associated image in response to a client timer event. 
  So, the effect would be that of a… slideshow – precisely!

Now, the control was showing up correctly in a test .aspx page even before my second coffee and before my kids woke up… brilliant!
Was it the second, or third one? … It must have been the second…
I couldn’t see any sun light outside yet…

Now the interesting part, the control’s properties and logic…

Control Properties ? 

• Width and Height – to make sure the control could be properly sized in different web pages.
• QueryText – I needed a string for the query that should be issued to Microsoft Live Search.
• MaxNumberOfImages  - to define the maximum number of images the client would request to the web service and, ultimately, to Microsoft Live Search.

That was it. I was determined to keep it simple…

Control Logic ?

A handful of statements to initialize the control, a few other lines for the presentation, just enough to arrange and scale the controls inside the panel based on the Width and Height defined by the user.
Then, I had to make sure the SlideShow extender would carry the right parameters for the web service invocation, namely: QueryText and MaxNumberOfImages.

Hmmm… the SlideShow’s ContextKey property used to pass information to the invoked web service is a string though…
you can’t pass the two properties just like that.
Not too bad though. I just had to serialize both properties and assign the serialized string to the ContextKey property. 
  You know? I used to hate serialization, but now Microsoft .NET offers plenty of choices to do it, it’s not fun yet.. but much better. 
  I just needed a wrapper object for the two properties.
  So, I created the Query object to carry that information and to implement the serialization.

Web Service

I developed of the web service in phases…

At first, I tested the client / server interaction, then I carried on with requesting images to Microsoft Live Search APIs.
  I started with a simple stub for the web service, encapsulating just enough logic so that it would return a few images taken from my web’s images directory…   Hey, it was not much, I know…, but that would do it for a first test of the service, and it would also show a slideshow on the client too.

That worked out quite well!
  By breakfast time, my control was invoking the web service, and showing a slide show of the returned images on the client. 
  The end to end lacked only the integration with Microsoft Live Search.
  I was almost done, wasn’t I? :-)

Plus, it was about time to enjoy some quality time with my family…
Yet, they were all sleeping… why would I wake them up?
And, Oh.. Noooo… :-)  it was snowing again!

Well,… I went downstairs to prepare a cup of coffee, while reading the documentation of Microsoft Live Search APIs.
  I had not made up my mind yet whether I would use the HTTP Get or SOAP as protocol. I knew HTTP would probably be a little bit lighter weight, but that meant I would need to deal with parsing some XML documents back and forth. Then, I opted to use SOAP, out of laziness I guess… the facility offered by the typed objects provided with the SOAP APIs was way too appealing.

Even more intriguing were the neatly assembled samples provided with the APIs. I had them working , and I adapted them within my web service code even before I finished my coffee… the third one!

Finally, I had a prototypical implementation of the end to end scenario that exercised the whole architecture.
And, it was working quite well.

However, a few doubts started crossing my mind when I got fancy with the queries using Live Search operators like site: or language: or location:. 
  These questions became more pressing when, with specific reference to image queries, I started using some other operators in order to filter results on image properties such as ImageAspectRatio (Tall, Wide, Square), ImageType (Photo, Graphics), etc… 
  I was a bit frustrated I had to write an application to do build a long and complicated query to interoperate with the Microsoft Live Search.
Truth to be told, everything was working fine, but my experience as a developer could have been better… 
  The reasons was that the components I had built so far, did not know anything about these operators. Their knowledge was only in my mind and hmm…. in Microsoft Live Search APIs’.
  And, I thought it was a pity none of my components would expose that knowledge in a more useful way.

I knew it!

All that had little to do with my little project.
  I was already thinking how Microsoft Live Search APIs could be extended and/or simplified… :-)

I could not help it though.  

I had to take another look at that Query wrapper. 
  Yep, its responsibilities could be expanded with great benefit for the overall solution.

But that was enough for the day… and for this part!

Getting Images from Live Search APIs – part 1

I don’t like the snow.
  When it is fresh, it is white and beautiful, but it is way too cold…
  Then, if you live in a city, it quickly gets dirty and muddy…
And, we had plenty this year in Seattle, especially around Christmas.

So, I’d rather stay home when it snows,  enjoying the family and, 
if possible, doing something cool… whatever happens to be cool for me at the time.

This time, I ended up doing some work for my little web site for fishing aficionados. A web I use more as a web developer fitness center than a real web app… right! go figure… :-)

Since I reviewed Microsoft’s Live Search APIs 2.0, a few days before the Christmas break, I thought it would be interesting to include some of the content they make available, like search results, news and images on my web’s pages.

Boy, these APIs make accessing Microsoft Live Search really easy!

You compose a query in a search request and you get a collection of results back. Both request and results are typed, i.e. images and news have different types, with specific properties, etc.. And, you can use different protocols, such as SOAP, XML, to communicate with the Live Search API service.

Building an application around them is quite simple. So, developers can really focus on how to implement the user scenarios.

For my web, I thought it would be cool to have an image slideshow, showing fishing photographs taken from those indexed on the net, within the context imposed by any given container page, yet picked in a somewhat random way and always fresh (making sure to properly show their source/credits).

I started envisioning something like this… Great fish, by the way!

So, let’s see… what are we looking at here?

A custom ASP.NET server control, a composite one, with an Ajax slide show extender to animate the images and interact with the user through the buttons… and some code to connect to the Microsoft Live Search service.

Yes, that would do it.

As a second thought, I would need to expose the application ID on the client Javascript code, hmmm… not good… not good!
   It is not that the AppID could not be sniffed on the net, but the idea of plainly exposing it, didn’t sound right.

More importantly, if my web had many users that would translate in many requests to Microsoft Live Search API, one per active client.
Yet… if two or more clients were looking at the same page – say the one about Alaska, i.e. issuing the same query (like: “Fishing Alaska”), wouldn’t I be able to cache the request/content on my web, before serving that page?

Gotcha!!

I just needed a service on my web, to support client requests and forward them to the Microsoft Live Search APIs and/or cache them and their results.

Perhaps two, three days of work for a solid prototype…

Sure! Why not?

After all, there were two feet of snow outside…

And so I did… and it was almost like I predicted.

The architecture it is working fine, and the results are neat.
Plus, I managed to create another couple of interesting components on the way…

And now that the snow melt for long, I thought I would share this experience with you. That is.

Stay tuned for the incoming parts…

Providing DSL users with context / guidance

Using GAT to extend consumption of DSL artifacts

DSL cross language integration

DSL constraint checking across languages