Getting Started with the Search REST API in SharePoint 2013 Preview

Posted Friday, September 7, 2012 10:33 AM by CoreyRoth

We have a brand new REST based API for interacting with Search in SharePoint 2013 Preview.  Unfortunately, there is not a lot of information out there yet on how to interact with it.  I have pieced together a couple of bits to help get you started.  If you are looking to bring Search into an HTML / JavaScript based application, you’ll be able to get started right away.  The first piece of the puzzle is putting together the right URL to access Search via REST.  To do this, we start with the server name and append /_api/search/query.  Just typing this into the browser will start giving you useful information.  For example:

http://server/_api/search/query

SearchRESTAPIDefault

If you look towards the bottom, you will see the Key SerializedQuery.  This actually shows you the parameters passed into the request.  It also provides you a hint as to what type of parameters you can pass to the REST interface.  The one that might immediately stand out is QueryText.  This is the actual search query.  Think of it as the equivalent of what you type into the search box.  There are a few other parameters that you can customize here as well such as the SummaryLength, MaxSnippetLength. and more.  Let’s try adding QueryText to our URL and passing in a value.

http://server/_api/search/query?querytext=SharePoint

SearchRESTAPIFailedQuery

It turns out the value always has to be enclosed in single quotes (‘) like this:

http://server/_api/search/query?querytext=’SharePoint’

Now, we get some results:

SearchRESTAPIResults

The search results themselves are included in the d:RelevantResults element.  It contains an element d:Table which has   Bare with me as I am going to post the XML for one of the results so that we can inspect it further.

<d:element m:type="SP.SimpleDataRow">

  <d:Cells>

    <d:element m:type="SP.KeyValue">

      <d:Key>Rank</d:Key>

      <d:Value>20.268159866333</d:Value>

      <d:ValueType>Edm.Double</d:ValueType>

    </d:element>

    <d:element m:type="SP.KeyValue">

      <d:Key>DocId</d:Key>

      <d:Value>31</d:Value>

      <d:ValueType>Edm.Int64</d:ValueType>

    </d:element>

    <d:element m:type="SP.KeyValue">

      <d:Key>WorkId</d:Key>

      <d:Value>31</d:Value>

      <d:ValueType>Edm.Int64</d:ValueType>

    </d:element>

    <d:element m:type="SP.KeyValue">

      <d:Key>Title</d:Key>

      <d:Value>Getting the most out of SharePoint Search</d:Value>

      <d:ValueType>Edm.String</d:ValueType>

    </d:element>

    <d:element m:type="SP.KeyValue">

      <d:Key>Author</d:Key>

      <d:Value>Corey Roth;SharePoint Setup</d:Value>

      <d:ValueType>Edm.String</d:ValueType>

    </d:element>

    <d:element m:type="SP.KeyValue">

      <d:Key>Size</d:Key>

      <d:Value>2425342</d:Value>

      <d:ValueType>Edm.Int64</d:ValueType>

    </d:element>

    <d:element m:type="SP.KeyValue">

      <d:Key>Path</d:Key>

      <d:Value>http://sp2010/Shared Documents/Getting the most out of SharePoint Search - SharePoint Saturday Denver.pptx</d:Value>

      <d:ValueType>Edm.String</d:ValueType>

    </d:element>

    <d:element m:type="SP.KeyValue">

      <d:Key>Description</d:Key>

      <d:Value>

        Template: Sam Moore; Silver Fox Productions, Inc.&#xD;

        Formatting:&#xD;

        Event Date: October 3-6th, 2011&#xD;

        Event Location: Anaheim, CA&#xD;

        Audience Type: Internal/External

      </d:Value>

      <d:ValueType>Edm.String</d:ValueType>

    </d:element>

    <d:element m:type="SP.KeyValue">

      <d:Key>Write</d:Key>

      <d:Value>2011-11-10T00:00:00.0000000</d:Value>

      <d:ValueType>Edm.DateTime</d:ValueType>

    </d:element>

    <d:element m:type="SP.KeyValue">

      <d:Key>CollapsingStatus</d:Key>

      <d:Value>0</d:Value>

      <d:ValueType>Edm.Int64</d:ValueType>

    </d:element>

    <d:element m:type="SP.KeyValue">

      <d:Key>HitHighlightedSummary</d:Key>

      <d:Value xml:space="preserve">Passed all &lt;c0&gt;SharePoint&lt;/c0&gt; 2010 certification exams &lt;ddd/&gt; Introduce Search in &lt;c0&gt;SharePoint&lt;/c0&gt; Online &lt;ddd/&gt; The talk will be slides with quite a few demos of &lt;c0&gt;SharePoint&lt;/c0&gt; Online features &lt;ddd/&gt; </d:Value>

      <d:ValueType>Edm.String</d:ValueType>

    </d:element>

    <d:element m:type="SP.KeyValue">

      <d:Key>HitHighlightedProperties</d:Key>

      <d:Value m:null="true" />

      <d:ValueType>Null</d:ValueType>

    </d:element>

    <d:element m:type="SP.KeyValue">

      <d:Key>contentclass</d:Key>

      <d:Value>STS_ListItem_DocumentLibrary</d:Value>

      <d:ValueType>Edm.String</d:ValueType>

    </d:element>

    <d:element m:type="SP.KeyValue">

      <d:Key>PictureThumbnailURL</d:Key>

      <d:Value m:null="true" />

      <d:ValueType>Null</d:ValueType>

    </d:element>

    <d:element m:type="SP.KeyValue">

      <d:Key>ServerRedirectedURL</d:Key>

      <d:Value m:null="true" />

      <d:ValueType>Null</d:ValueType>

    </d:element>

    <d:element m:type="SP.KeyValue">

      <d:Key>ServerRedirectedEmbedURL</d:Key>

      <d:Value m:null="true" />

      <d:ValueType>Null</d:ValueType>

    </d:element>

    <d:element m:type="SP.KeyValue">

      <d:Key>ServerRedirectedPreviewURL</d:Key>

      <d:Value m:null="true" />

      <d:ValueType>Null</d:ValueType>

    </d:element>

    <d:element m:type="SP.KeyValue">

      <d:Key>FileExtension</d:Key>

      <d:Value>pptx</d:Value>

      <d:ValueType>Edm.String</d:ValueType>

    </d:element>

    <d:element m:type="SP.KeyValue">

      <d:Key>ContentTypeId</d:Key>

      <d:Value>0x010100B1CF83A7F86DFC468C975FFF33126DFD</d:Value>

      <d:ValueType>Edm.String</d:ValueType>

    </d:element>

    <d:element m:type="SP.KeyValue">

      <d:Key>ParentLink</d:Key>

      <d:Value>http://sp2010/Shared Documents/Forms/AllItems.aspx</d:Value>

      <d:ValueType>Edm.String</d:ValueType>

    </d:element>

    <d:element m:type="SP.KeyValue">

      <d:Key>ViewsLifeTime</d:Key>

      <d:Value m:null="true" />

      <d:ValueType>Null</d:ValueType>

    </d:element>

    <d:element m:type="SP.KeyValue">

      <d:Key>ViewsRecent</d:Key>

      <d:Value m:null="true" />

      <d:ValueType>Null</d:ValueType>

    </d:element>

    <d:element m:type="SP.KeyValue">

      <d:Key>SectionNames</d:Key>

      <d:Value xml:space="preserve">Getting the most out of SharePoint Search&#xD;

;Getting the most out of SharePoint Search&#xD;

;Corey Roth&#xD;

About me&#xD;

;Key Theme&#xD;

;SharePoint is not a…&#xD;

;SharePoint is a…&#xD;

;Challenges with Search&#xD;

;Agenda&#xD;

;Key Takeaways&#xD;

;You have a choice…&#xD;

;What can search index?&#xD;

;Search in SharePoint&#xD;

;Components of Search&#xD;

;Finding things easier…&#xD;

;Improve search with queries&#xD;

;Built-in Managed Properties&#xD;

;Segmenting results with Scopes&#xD;

;Querying Search and Scopes&#xD;

;Provide more search options&#xD;

;Many options for displaying scopes&#xD;

</d:Value>

      <d:ValueType>Edm.String</d:ValueType>

    </d:element>

    <d:element m:type="SP.KeyValue">

      <d:Key>SectionIndexes</d:Key>

      <d:Value>1;2;3;4;5;6;7;8;9;10;11;12;13;14;15;16;17;18;19;20</d:Value>

      <d:ValueType>Edm.String</d:ValueType>

    </d:element>

    <d:element m:type="SP.KeyValue">

      <d:Key>SiteLogo</d:Key>

      <d:Value m:null="true" />

      <d:ValueType>Null</d:ValueType>

    </d:element>

    <d:element m:type="SP.KeyValue">

      <d:Key>SiteDescription</d:Key>

      <d:Value m:null="true" />

      <d:ValueType>Null</d:ValueType>

    </d:element>

    <d:element m:type="SP.KeyValue">

      <d:Key>deeplinks</d:Key>

      <d:Value m:null="true" />

      <d:ValueType>Null</d:ValueType>

    </d:element>

    <d:element m:type="SP.KeyValue">

      <d:Key>importance</d:Key>

      <d:Value>0</d:Value>

      <d:ValueType>Edm.Int64</d:ValueType>

    </d:element>

    <d:element m:type="SP.KeyValue">

      <d:Key>SiteName</d:Key>

      <d:Value>http://sp2010</d:Value>

      <d:ValueType>Edm.String</d:ValueType>

    </d:element>

    <d:element m:type="SP.KeyValue">

      <d:Key>IsDocument</d:Key>

      <d:Value>true</d:Value>

      <d:ValueType>Edm.Boolean</d:ValueType>

    </d:element>

    <d:element m:type="SP.KeyValue">

      <d:Key>LastModifiedTime</d:Key>

      <d:Value>2011-11-10T00:00:00.0000000</d:Value>

      <d:ValueType>Edm.DateTime</d:ValueType>

    </d:element>

    <d:element m:type="SP.KeyValue">

      <d:Key>FileType</d:Key>

      <d:Value>pptx</d:Value>

      <d:ValueType>Edm.String</d:ValueType>

    </d:element>

    <d:element m:type="SP.KeyValue">

      <d:Key>IsContainer</d:Key>

      <d:Value>false</d:Value>

      <d:ValueType>Edm.Boolean</d:ValueType>

    </d:element>

    <d:element m:type="SP.KeyValue">

      <d:Key>WebTemplate</d:Key>

      <d:Value m:null="true" />

      <d:ValueType>Null</d:ValueType>

    </d:element>

    <d:element m:type="SP.KeyValue">

      <d:Key>SecondaryFileExtension</d:Key>

      <d:Value>pptx</d:Value>

      <d:ValueType>Edm.String</d:ValueType>

    </d:element>

    <d:element m:type="SP.KeyValue">

      <d:Key>OriginalPath</d:Key>

      <d:Value>http://sp2010/Shared Documents/Getting the most out of SharePoint Search - SharePoint Saturday Denver.pptx</d:Value>

      <d:ValueType>Edm.String</d:ValueType>

    </d:element>

    <d:element m:type="SP.KeyValue">

      <d:Key>DisplayAuthor</d:Key>

      <d:Value>Corey Roth;SharePoint Setup</d:Value>

      <d:ValueType>Edm.String</d:ValueType>

    </d:element>

    <d:element m:type="SP.KeyValue">

      <d:Key>Created</d:Key>

      <d:Value>2012-07-26T23:21:29.0000000</d:Value>

      <d:ValueType>Edm.DateTime</d:ValueType>

    </d:element>

    <d:element m:type="SP.KeyValue">

      <d:Key>PeopleInMedia</d:Key>

      <d:Value></d:Value>

      <d:ValueType>Edm.String</d:ValueType>

    </d:element>

    <d:element m:type="SP.KeyValue">

      <d:Key>MediaDuration</d:Key>

      <d:Value m:null="true" />

      <d:ValueType>Null</d:ValueType>

    </d:element>

    <d:element m:type="SP.KeyValue">

      <d:Key>PictureWidth</d:Key>

      <d:Value m:null="true" />

      <d:ValueType>Null</d:ValueType>

    </d:element>

    <d:element m:type="SP.KeyValue">

      <d:Key>PictureHeight</d:Key>

      <d:Value m:null="true" />

      <d:ValueType>Null</d:ValueType>

    </d:element>

    <d:element m:type="SP.KeyValue">

      <d:Key>DefaultEncodingURL</d:Key>

      <d:Value>http://sp2010/Shared%20Documents/Getting%20the%20most%20out%20of%20SharePoint%20Search%20-%20SharePoint%20Saturday%20Denver.pptx</d:Value>

      <d:ValueType>Edm.String</d:ValueType>

    </d:element>

    <d:element m:type="SP.KeyValue">

      <d:Key>ExternalMediaURL</d:Key>

      <d:Value m:null="true" />

      <d:ValueType>Null</d:ValueType>

    </d:element>

    <d:element m:type="SP.KeyValue">

      <d:Key>UserEncodingURL</d:Key>

      <d:Value m:null="true" />

      <d:ValueType>Null</d:ValueType>

    </d:element>

    <d:element m:type="SP.KeyValue">

      <d:Key>Community_MembersCount</d:Key>

      <d:Value m:null="true" />

      <d:ValueType>Null</d:ValueType>

    </d:element>

    <d:element m:type="SP.KeyValue">

      <d:Key>Community_RepliesCount</d:Key>

      <d:Value m:null="true" />

      <d:ValueType>Null</d:ValueType>

    </d:element>

    <d:element m:type="SP.KeyValue">

      <d:Key>Community_TopicsCount</d:Key>

      <d:Value m:null="true" />

      <d:ValueType>Null</d:ValueType>

    </d:element>

    <d:element m:type="SP.KeyValue">

      <d:Key>ReplyCount</d:Key>

      <d:Value>0</d:Value>

      <d:ValueType>Edm.Int64</d:ValueType>

    </d:element>

    <d:element m:type="SP.KeyValue">

      <d:Key>LikesCount</d:Key>

      <d:Value m:null="true" />

      <d:ValueType>Null</d:ValueType>

    </d:element>

    <d:element m:type="SP.KeyValue">

      <d:Key>Discussion_BestAnswerID</d:Key>

      <d:Value m:null="true" />

      <d:ValueType>Null</d:ValueType>

    </d:element>

    <d:element m:type="SP.KeyValue">

      <d:Key>Discussion_Category</d:Key>

      <d:Value m:null="true" />

      <d:ValueType>Null</d:ValueType>

    </d:element>

    <d:element m:type="SP.KeyValue">

      <d:Key>Discussion_Post</d:Key>

      <d:Value m:null="true" />

      <d:ValueType>Null</d:ValueType>

    </d:element>

    <d:element m:type="SP.KeyValue">

      <d:Key>Discussion_LikesCount</d:Key>

      <d:Value m:null="true" />

      <d:ValueType>Null</d:ValueType>

    </d:element>

    <d:element m:type="SP.KeyValue">

      <d:Key>ListItemID</d:Key>

      <d:Value>6</d:Value>

      <d:ValueType>Edm.String</d:ValueType>

    </d:element>

    <d:element m:type="SP.KeyValue">

      <d:Key>FullPostBody</d:Key>

      <d:Value m:null="true" />

      <d:ValueType>Null</d:ValueType>

    </d:element>

    <d:element m:type="SP.KeyValue">

      <d:Key>PostAuthor</d:Key>

      <d:Value m:null="true" />

      <d:ValueType>Null</d:ValueType>

    </d:element>

    <d:element m:type="SP.KeyValue">

      <d:Key>RootPostOwnerID</d:Key>

      <d:Value m:null="true" />

      <d:ValueType>Null</d:ValueType>

    </d:element>

    <d:element m:type="SP.KeyValue">

      <d:Key>RootPostID</d:Key>

      <d:Value m:null="true" />

      <d:ValueType>Null</d:ValueType>

    </d:element>

    <d:element m:type="SP.KeyValue">

      <d:Key>AttachmentType</d:Key>

      <d:Value m:null="true" />

      <d:ValueType>Null</d:ValueType>

    </d:element>

    <d:element m:type="SP.KeyValue">

      <d:Key>AttachmentURI</d:Key>

      <d:Value m:null="true" />

      <d:ValueType>Null</d:ValueType>

    </d:element>

    <d:element m:type="SP.KeyValue">

      <d:Key>MicroBlogType</d:Key>

      <d:Value m:null="true" />

      <d:ValueType>Null</d:ValueType>

    </d:element>

    <d:element m:type="SP.KeyValue">

      <d:Key>ModifiedBy</d:Key>

      <d:Value>

        Corey Roth

 

        SharePoint Setup

      </d:Value>

      <d:ValueType>Edm.String</d:ValueType>

    </d:element>

    <d:element m:type="SP.KeyValue">

      <d:Key>RootPostUniqueID</d:Key>

      <d:Value m:null="true" />

      <d:ValueType>Null</d:ValueType>

    </d:element>

    <d:element m:type="SP.KeyValue">

      <d:Key>Tags</d:Key>

      <d:Value></d:Value>

      <d:ValueType>Edm.String</d:ValueType>

    </d:element>

    <d:element m:type="SP.KeyValue">

      <d:Key>ImageDateCreated</d:Key>

      <d:Value m:null="true" />

      <d:ValueType>Null</d:ValueType>

    </d:element>

    <d:element m:type="SP.KeyValue">

      <d:Key>PictureURL</d:Key>

      <d:Value m:null="true" />

      <d:ValueType>Null</d:ValueType>

    </d:element>

    <d:element m:type="SP.KeyValue">

      <d:Key>ResultTypeIdList</d:Key>

      <d:Value>2;6</d:Value>

      <d:ValueType>Edm.String</d:ValueType>

    </d:element>

    <d:element m:type="SP.KeyValue">

      <d:Key>PartitionId</d:Key>

      <d:Value>0c37852b-34d0-418e-91c6-2ac25af4be5b</d:Value>

      <d:ValueType>Edm.Guid</d:ValueType>

    </d:element>

    <d:element m:type="SP.KeyValue">

      <d:Key>UrlZone</d:Key>

      <d:Value>0</d:Value>

      <d:ValueType>Edm.Int32</d:ValueType>

    </d:element>

    <d:element m:type="SP.KeyValue">

      <d:Key>AAMEnabledManagedProperties</d:Key>

      <d:Value>HierarchyUrl;OrgParentUrls;OrgUrls;OriginalPath;Path;recommendedfor;SitePath</d:Value>

      <d:ValueType>Edm.String</d:ValueType>

    </d:element>

    <d:element m:type="SP.KeyValue">

      <d:Key>ResultTypeId</d:Key>

      <d:Value>2</d:Value>

      <d:ValueType>Edm.Int32</d:ValueType>

    </d:element>

    <d:element m:type="SP.KeyValue">

      <d:Key>RenderTemplateId</d:Key>

      <d:Value>~sitecollection/_catalogs/masterpage/Display Templates/Search/Item_PowerPoint.js</d:Value>

      <d:ValueType>Edm.String</d:ValueType>

    </d:element>

    <d:element m:type="SP.KeyValue">

      <d:Key>piSearchResultId</d:Key>

      <d:Value>1_1</d:Value>

      <d:ValueType>Edm.String</d:ValueType>

    </d:element>

  </d:Cells>

</d:element>

As you can see, we now get a ton of information back from Search for a given search result.  Let me point out some of the more interesting values.  We have the usual values such as Title, Path, Author, Write (Modified Date), and HitHighlightedSummary.  However, we also get a ton of new information.  For images, you will get a PictureThumbnailUrl to allow you to easily show a thumbnail.  This particular result is a PowerPoint and search understands the individual sections inside it now which you will see in SectionNames.  SiteName provides the site hosting the item.  Tags will provide any use of the Enterprise Keywords field.  You also get a heap of social information about the item as well such as how many likes.  Lastly, the RenderTemplateId tells you which template the result source is using to display it on the search results page.  This is just one example, but you can see we get a lot of useful information about the search.

Looking at the XML in the browser is a great way to get familiar with what the API has to offer.  When you are ready to start developing, it is very easy to take advantage of the REST API using JavaScript.  You can do this with the $.ajax() method in jQuery and pass in the URL you used in the browser.  You want to use the GET method and pass in a header telling it you want the results back as json.  They have a good example of how this works on code.msdn.microsoft.com.  Specifically, take a look at App.js in the example to see the code in action.  It’s pretty simple.

If you want to take advantage of the REST API from C# or another .NET language, that is another story though.  I haven’t been able to add a service reference for the REST API.  All of the server side code examples I have seen call the REST API using HttpWebRequest which requires no less than 60 lines of code or so.  I am hoping there is a better way but I haven’t seen one yet.  If you have had better luck be sure and let me know.

Filed under: , , , ,

Comments

No Comments

Leave a Comment

(required)
(required)
(optional)
(required)