Docs / API / Full-text search

Search API¶

The Flotiq API provides a powerful search engine, which is a wrapper for ElasticSearch queries. We tried to balance between resembling the ES API (for those, who already know it) and keeping it simple and cohesive with Flotiq API.

You can use the search engine via the GET /api/v1/search endpoint to search through all Content Objects.

Search parameters

Name	Type	Description
q	string	Query (required).
page	number	Listing page number
limit	number	Results per page
content_type[]	array	Restrict search to content types set The expected format: `content_type[]=type1&content_type[]=type2`
aggregate_by[]	array	Fields to aggregate results. The expected format: `aggregate_by[]=name&aggregate_by[]=slug`
aggregate_by_numeric[]	array	Fields to aggregate results by numeric values. The expected format: `aggregate_by_numeric[]=price&aggregate_by_numeric[]=count`
filters[]	array	Filter by object properties. The expected format: `filters[propertyName]=value1&filters[propertyName2]=value2`. Follows the rules of the ElasticSearch Query String Query.
geo_filters	array	Filter by object geolocation properties. Example value: `geo_distance,1.50km,40.1,-19.2` which means: `filter name`, `distance`, `latitude` and `longitude`. For more information see ElasticSearch docs. Only the `geo_distance` query is supported.
post_filters	array	Filter by object properties. Use it when you want aggregated counts without filters applied. Expected format: `filters[propertyName]=value1&filters[propertyName2]=value2`
fields[]	array	List of content fields to be searched. The expected format: `fields[]=field1&fields[]=field2`
order_by	string	Name of the field to sort results by (they are always primarily sorted by `_score`)
order_direction	string	Direction of sorting (`asc` for ascending or `desc` for descending, default `asc`)
random_seed	number	Seed for random sorting order (overrides `order_by`)

Example: Search for "Flotiq" in posts¶

Request:

GET https://api.flotiq.com/api/v1/search?q=Flotiq&content_type[]=post

Response:

{
    "total_count": 1,
    "count": 1,
    "total_pages": 1,
    "current_page": 1,
    "summary": {
        "aggregations": []
    },
    "data": [
        {
            "item": {
                "lead": "You model, author and consume your content, your way. Flotiq is an API-first CMS that takes care of hosting, securing and scaling to guarantee your content is always on.",
                "object_data": "{\"id\": \"post-900923\", \"lead\": \"You model, author and consume your content, your way. Flotiq is an API-first CMS that takes care of hosting, securing and scaling to guarantee your content is always on.\", \"slug\": \"your-content-your-way\", \"title\": \"Your content, your way!\", \"public\": true, \"content\": \"Flotiq provides an easy way to describe your content, populate your system with large amounts of data and consume it.\", \"internal\": {\"createdAt\": \"2020-01-22T14:34:36+00:00\", \"deletedAt\": \"\", \"updatedAt\": \"2020-01-22T14:34:36+00:00\", \"contentType\": \"post\"}}",
                "organization_id": "ea283dbe-3205-11ea-aed7-0242ac130003",
                "deleted_at": null,
                "content": "Flotiq provides an easy way to describe your content, populate your system with large amounts of data and consume it.",
                "id": "post-900923",
                "slug": "your-content-your-way",
                "updated_at": null,
                "content_type_definition_id": "6c8f42d8-3208-11ea-aed7-0242ac130003",
                "created_at": "2020-01-22T14:34:36.000Z",
                "@timestamp": "2020-01-22T14:34:40.119Z",
                "title": "Your content, your way!",
                "public": true,
                "internal": {
                    "deletedAt": "",
                    "updatedAt": "2020-01-22T14:34:36+00:00",
                    "contentType": "post",
                    "createdAt": "2020-01-22T14:34:36+00:00"
                }
            },
            "score": 19.395857
        }
    ]
}

Limit the search to a specific Content Type¶

You can easily limit the search to a specific Content Type by providing its name in the content_type[] argument.

Order by content field¶

You can sort the results from the search endpoint by Content Type's field using an "order_by" parameter:

Example

GET https://api.flotiq.com/api/v1/search?q=Flotiq&content_type[]=post&order_by=date

Keep in mind that ordering by a field that is nested in the object input type (list) is not possible.

Note

You may also use the .keyword suffix for other data than text fields, for example, if you are using an id field that uses a number type in Flotiq, you may still want to consider using the .keyword suffix when ordering by such field. This will result in slightly faster searching and will sort objects by id alphabetically, not from the highest number to the lowest.

Limit the search to a specific field¶

You can restrict queries to a specific field by passing the fields[] argument, for example, fields[]=name would only search in the name field.

Increase scoring for specific fields¶

If you'd like to search in several fields but give better score to results that match the query in a specific field - you can use ElasticSearch's field boosting to promote fields. In order to do that - pass the fields and their weights through the fields[] argument, for example, fields[]=title^3&fields[]=content^1 would assign a weight of 3 to the title field and a weight of 1 to the content field.

Aggregate results by field¶

If you'd like to display faceted results of your searches you can use the aggregate_by[] param. Add aggregate_by[]=category to aggregate by the category field. This works best with fields that have discreet values (like status, category, etc), and only works with string fields, if you wish to aggregate with numeric fields, use aggregate_by_numeric[] param.

Get random content objects¶

You can use the random_seed parameter to retrieve random content objects. The random_seed parameter accepts a number value for a random number generator. This will sort data in random order, so if you want for example to retrieve two random content objects, you can pass any number to random_seed and set the limit parameter value to 2.

Note

Since random_seed is changing the order of retrieved content objects, it will override the value of your order_by parameter.

Increase scoring for specific content types¶

Note

Index boosting is available in Custom plan tier.

Index boosting allows you to prioritize results from specific indices when performing searches across multiple content types (CTDs). This feature increases the score of results from certain indices based on user-defined weights, which is useful when some CTDs are more relevant than others.

Example

Pass the indices_boost parameter in your query to boost specific CTDs:

/api/v1/search?indices_boost[ctd1Name]=2&indices_boost[ctd2Name]=1.5

ctd1Name, ctd2Name – names of the CTDs.
2, 1.5 – boost values (higher means more weight)