Search API

The Search API runs a query against a specified search platform and returns the results in either XML or JSON format.

Resource URI

/twigkit/api/core/services/platform

GET search/{platform}

Sends a query to the named platform and returns the response as either an XML document or a JSON object. The search query is described by one or more request parameters.

Path parameters

platform
Required
The configuration name of the search platform that should process the query.
Example values: my.platform, platform.solr.news

Note
The platform configuration must have the property readOnly: false.

Query parameters

The search query that is submitted to the platform is described using one or more of these query parameters:

q - Query term (string)
Specifies the query term to use. This will override defaultQuery parameter of the search platform, which is the default query term used when q is omitted.

rpp - Results per page (integer)
The number of results to display per page.
Default: 10

max - Maximum number of search results (integer)
The maximum number of results to evaluate.
Default: -1, which means no upper limit

p - Page of search results to fetch (integer)
Set the page of results to retrieve. Default values is 1 (1-based index) which would display the first page of results, which includes rpp documents.
Default: 1

fa - Fields to facet on (comma-separated list)
Specifies which facets should be requested from the search engine. The list of facets is requested as a comma-separated list without spaces (for example, f=cat,inStock). Will override the defaultFacets parameter of the search platform.

fi - Fields to return in search results (comma-separated list)
A comma-separated list of fields which should be returned in the search response for every document.

s - List of fields to sort on (string, multi-valued)
Specifies fields and order for sorting. Sort order is specified by one of two characters: + for ascending and - for descending. To sort ascending by the field price, the sort would be specified as s=+price for example. Multi-dimensional sorting is also supported with repeated occurrences of the s parameter. For example, to sort by the price field in ascending order and then by the sku field in descending order, you could use &s=+price&s=-sku in a URL.

v - Document view (string)
Set which search engine view to use. Behaviour will vary by the search engine used.

f - Search filters (string, multi-valued)
Constraints that should be applied to the search query. Multiple filters are specified by repeating the f query parameter. See details on Query filter representation below.

c - Custom search engine parameters (string)
This parameter lets you send engine-specific custom parameters to the underlying search platform. Parameters are specified using the format parameter[value] for a single parameter. To submit multiple custom parameters use multiple instances of the c parameter, for example, c=parameter1[value1]&c=parameter2[value2].

t - Query type (string)
Specifies how to interpret multiple query terms. Takes one of three values: any (combines the terms using a Boolean OR), all (combines the terms using Boolean AND), or adv (interpret the query terms as a native query expression, specific to the platform used). For example, take the query apple ipod. With t=all only documents containing both the terms will be returned, whereas with type=any any document containing either term will be returned.
Default: any

Query filter representation

Query filters are specified using the format fieldName[value]['display name']. The ['display name'] part is optional in all cases.

For example, adding f=location['san francisco'] to a query will restrict the results to those documents that have 'san francisco' as a location field value. Multiple filters can be specified by adding multiple f parameters, for example f=location['san francisco']&f=first_name['john'].

Important
If the filter value is a string, surround the string with single or double quotes. All other primitives and dates should omit quotes around the filter value.

For example:

  • Filtering on a string value: &f=stringField['My String']["String example"]

  • Filtering on an integer value:`&f=integerField[123]["Integer example"]`

  • Filtering on a floating point value: &f=doubleOrFloatField[123.45]["Double example"]

Filters can also be used to define range queries for numbers, dates and strings. The start and end range of a filter are comma-separated and either one can be omitted to signify open-ended intervals. For example f=salary[1000,100000] will search the salary field for values between 1,000 and 100,000, both inclusive. Dates are specified using the format yyyy-MM-dd’T’HH:mm:ss.

To exclude the upper or lower limit of a range, it is possible to replace the [ and ] with a ( and ) to identify non-inclusive endpoints. For example: f=date_field[yyyy-MM-dd’T’HH:mm:ss,yyyy-MM-dd’T’HH:mm:ss)["Date range excluding upper limit"].

For more details on query filters, read the formal syntax definition or details of how to combine multiple filters using Boolean logic.

Example requests

Find all documents that match the "space cars" query term. The response should include only the title field of each document with at most 10 results per page:

GET /twigkit/api/core/services/platform/search/platforms.solr.news?q=space%20cars&rpp=10&fi=title HTTP/1.1
Accept: application/xml

<response xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" page="1" time="188">
    <query context="" rpp="10" max="-1" page="1" type="any" fields="title" view="" autoCorrected="false">
        <val>
            <act xsi:type="xs:string">space cars</act>
            <dsp>space cars</dsp>
        </val>
        <sorts/>
        <user id="admin" name="admin">
            <roles>
                <role>
                    <name>
                        <act xsi:type="xs:string">ADMIN</act>
                        <dsp>ADMIN</dsp>
                    </name>
                </role>
            </roles>
        </user>
        <custom/>
        <other/>
        <filters/>
    </query>

    <hits>
        <act xsi:type="xs:long">1</act>
        <dsp>1</dsp>
    </hits>

    <results>
        <result id="UIOUS#1" score="1.519731">
            <fields>
                <fld name="score">
                    <val>
                        <act xsi:type="xs:float">1.519731</act>
                        <dsp>1.519731</dsp>
                    </val>
                </fld>
                <fld name="title">
                    <val>
                        <act xsi:type="xs:string">Future Flyers: Pushing Forward for Personal Aircraft (SPACE.com)</act>
                        <dsp>Future Flyers: Pushing Forward for Personal Aircraft (SPACE.com)</dsp>
                    </val>
                </fld>
            </fields>
            <related/>
        </result>
        <result id="UIOUS#2" score="1.4792">
            <fields>
                <fld name="score">
                    <val>
                        <act xsi:type="xs:float">1.4792</act>
                        <dsp>1.4792</dsp>
                    </val>
                </fld>
                <fld name="title">
                    <val>
                        <act xsi:type="xs:string">NASA and Boeing Push for Flying Cars</act>
                        <dsp>NASA and Boeing Push for Flying Cars</dsp>
                    </val>
                </fld>
            </fields>
            <related/>
        </result>

    </results>
</response>

The same request, now calling for a response in JSON format:

GET /twigkit/api/core/services/platform/search/platforms.solr.news?q=space%20cars&amp;rpp=10&amp;fi=title HTTP/1.1
Accept: application/jsonrequest

{
 "query":{
 "context":"",
 "page":1,
 "sorts":[],
 "filters":[],
 "type":"any",
 "user":{"id":"admin","name":"admin","roles":[{"name":"ADMIN"}]},
 "fields":"title",
 "view":"",
 "autoCorrected":false,
 "transientParameters":[],
 "val":"space cars",
 "rpp":10,
 "max":-1,
 "custom":{},
 "other":{}
 },
 "hits":§,
 "page":1,
 "results":[{
 "result": {
 "id":"UIOUS#1",
 "fields":{
 "score":{"name":"score","val":[1.519731]},
 "title":{"name":"title","val":["Future Flyers: Pushing Forward for Personal Aircraft (SPACE.com)"]}
 },
 "related":[],
 "score":1.519731
 },
 "result": {
 "id":"UIOUS#2",
 "fields":{
 "score":{"name":"score","val":[1.4792]},
 "title":{"name":"title","val":["NASA and Boeing Push for Flying Cars"]}
 },
 "related":[],
 "score":1.4792
 }
 }],
 "time":128
}

Value objects

Value objects are always serialised as an array as displayed by the field object below:

"title":{
    "name":"title",
    "val":[
        "NASA and Boeing Push for Flying Cars"
    ]
}

POST search/{platform}

Sends a query to the given platform and outputs the response as either an XML document or a JSON object. This method works exactly as the GET method, above, except here the search query is given by parameters included in the body of a POST request.

Path parameters

platform
Required
The configuration name of the search platform that should process the query.
Example values: my.platform, platform.solr.news

Note
The platform configuration must have the property readOnly: false.

POST parameters

The search query that is submitted to the platform is specified using standard search query parameters that should be included in the body of the POST request (after the headers).