|
|
|
Dovetail Seeker exists to enable search against your Dovetail/Clarify CRM application. This API accepts GET or POST actions and executes searches against the index created by the indexing applications and returns results in JSON format.
Suggested Usages:
Page search result for searches returning many results.
Sort search results by custom fields.
Returning custom field values with search results.
Simple Example
Request:
GET /seeker/search?query=test
Response:
{"SearchResults":[<elided for sake of brevity>],"TotalNumberOfResults":0,"RequestedNumberOfResults":10,"StartResultIndex":0,"SearchQuery":"test","Exception":null,"LastIndexUpdateTimestamp":"2008-10-02T11:16:23"}
POST Example
Your application can use both GET and POST HTTP actions to execute search queries. The example below uses a JSON payload to transmit the query parameters. You could also use a regular web form POSTS (application/x-www-form-urlencoded).
Request:
POST /seeker/search
Headers:
Content-Type: application/json
Payload:
{ query: "test" }
Response:
{"SearchResults":[<elided for sake of brevity>],"TotalNumberOfResults":0,"RequestedNumberOfResults":10,"StartResultIndex":0,"SearchQuery":"test","Exception":null,"LastIndexUpdateTimestamp":"2008-10-02T11:16:23"}
Pagination Example
It is common that search clients will wish to allow pagination of search results.
Request:
GET /seeker/search?query=VPN&resultCount=1&startResultIndex=2
Response:
{"SearchResults":[<elided for sake of brevity>],"TotalNumberOfResults":2,"RequestedNumberOfResults":1,"StartResultIndex":0,"SearchQuery":"VPN","Exception":null,"LastIndexUpdateTimestamp":"2008-10-02T11:16:23"}
Result Sorting Example
Search results by default are sorted by relevancy. Sometimes that is not exactly what you want. It is possible to sort search results by a single custom field value.
Note: For a custom field to be sortable it's definition in the custom field document specification must have tokenization turned off.
Request:
GET /seeker/search?query=VPN&sortedByField=firstName&isSortedAscending=true
Response:
{"SearchResults":[<elided, yet sorted>],"TotalNumberOfResults":22,"RequestedNumberOfResults":10,"StartResultIndex":0,"SearchQuery":"Robert","Exception":null,"LastIndexUpdateTimestamp":"2008-10-02T11:16:23"}
Return Custom Fields Example
Custom field values are normally not returned with search results. It may be desirable in some situations to have custom field values returned with search results. To accomplish this you simply include one or more returnCustomField parameters with the search request.
Request:
GET /seeker/search?query=domain:case+AND+blue&returnCustomField=site&returnCustomField=contact
Response:
{"SearchResults":...,"CustomFields":{"site":"Dovetail Software","contact":"James Miller"}}]...
Search service parameters for /search
Parameter |
Required |
Default |
Description |
query |
yes |
n/a |
The search query |
resultCount |
no |
10 |
The number of results to return. Could also be considered the page size. |
startResultIndex |
no |
0 |
The index of the first search result to return. Used for pagination. |
maximumSummaryLength |
no |
n/a |
The maximum number of characters allowed in the Summary field of any search result. The goal of this optional parameter is to allow the client to control the size of the payload before it is transmitted. |
returnCustomField |
no |
n/a |
The custom fields in the search index are not normally returned with search results. Requests including this parameter will have all search results attempt to locate a field in the search index matching the parameter value. Note: Multiple returnCustomField parameters can exist per request. |
sortedByField |
no |
n/a |
Sort search results by this search index field. Note the field used for sorting cannot be Tokenized. You can control tokenization in the document specification. |
isSortedAscending |
no |
false |
When search results are being sorted by a field. This optional parameter controls the sort order. |
Search Results
The response returned by the Seeker web service is a collection of data encoded in JSON format. The search results themselves are wrapped in an envelope called Search Results Information which contains data about what was searched and what results are available.
An example search result:
{"SearchResults":[{"Score":0.5498657,"Domain":"solution","Id":"2","Title":" I can't connect to the VPN Server with my VPN Client","Summary":" Users are unable to connect to WinRoute using the VPN Client."}],"TotalNumberOfResults":2,"RequestedNumberOfResults":1,"StartResultIndex":0,"SearchQuery":"VPN","Exception":null,"LastIndexUpdateTimestamp":"2008-10-02T11:16:23"}
The search service returns a wrapper around the search results containing information about what was searched and what details are available.
Property |
Description |
Search Results |
An array of search result JSON objects. |
TotalNumberOfResults |
The total number of search results that matched the search term. |
RequestedNumberOfResults |
The number of results requested. This will match the resultCount request parameter. |
StartResultIndex |
The index of the first search result returned. This will match the startResultIndex request parameter. |
SearchQuery |
The search query. This will match the query request parameter |
Exception |
Only populated when something went wrong during the search process. |
LastIndexUpdateTimestamp |
When the search index was last updated. |
Zero or more search results can be returned by a search ordered by diminishing relevance.
Property |
Example |
Description |
Score |
.5498 |
A rating of how relevant the result is to the search term(s). A value between 0 and 1. |
Domain |
solution |
The type of search result being returned. |
Id |
2 |
Identifier of the search result. |
Title |
I can't connect to the VPN Server |
Title of the search result. |
Summary |
Users are unable to connect to WinRoute using the VPN Client. |
A summary of the search result. |
See Also |
Next |