DatoCMS Site Search

Perform searches via API

Important: Before you can perform a site search request via API, you must first set up a search index. Please see Configuration for setup instructions.

Once you've configured the search index, we can start performing search requests to our API to present relevant results to your visitors.

Obtaining an API token

To do that, first you need to generate an API token with the proper permissions. Go to Settings > Roles and create a new role with just the Can perform Site Search API calls permission checked.

You can then create a new API token associating it with the role you just created:

Awesome! Let's test if everything is working by making our first search request.

Performing searches

Our Content Management API offers a REST endpoint to perform search requests: please refer to its reference page to know which parameter you can pass.

The easiest way to use the endpoint is through our JavaScript clients. Depending on the environment where you're running your code, you can install the @datocms/cma-client-browser or the @datocms/cma-client-node npm package:

1
import { buildClient } from '@datocms/cma-client-browser';
2

3
const client = buildClient({ apiToken: '<YOUR_API_TOKEN>' });
4

5
const { data: searchResults, meta } = await client.searchResults.rawList({
6
  filter: {
7
    fuzzy: true,
8
    query: 'term to search',
9
    search_index_id: '4324',
10
    locale: 'it',
11
  },
12
  page: {
13
    limit: 20,
14
    offset: 0,
15
  },
16
});
17

18
console.log(`Total results: ${meta.total_count}`);
19
console.log(JSON.stringify(searchResults, null, 2));

Make sure to always specify the `search_index_id` parameter!

If you have multiple search indexes, you need to specify the filter: { search_index_id } parameter. You can find the search index ID as the last number of the search index URL on the dashboard or in the upper right corner of the search index settings. While, technically speaking, you can omit this parameter if you only have one build trigger, it is strongly suggested that you always pass it.

Want more results? Activate fuzzy search

When the fuzzy parameter is passed, our search engine will find strings that approximately match the query provided. For instance, strings like florence will be matched, even if the query is florance.

Let's take a look at how a search result looks like:

1
{
2
  "type": "search_result",
3
  "id": "12adNIIB8rFJF1DoTgCk",
4
  "attributes": {
5
    "title": "Florence Apartments for Rent | Long Term Student Accommodation Rentals",
6
    "body_excerpt": "Finding a place to live while planning to study abroad in Florence can be both exciting and challenging. With this in mind, Housing in Florence assists you in finding conveniently-located housing based...",
7
    "url": "http://www.website.com/some-page",
8
    "score": 11.3,
9
    "highlight": {
10
      "title": [
11
        "[h]Florence[/h] Apartments for Rent | Long Term Student Accommodation Rentals"
12
      ],
13
      "body": [
14
        "All our student accommodation and apartments in [h]Florence[/h] are fully"
15
      ]
16
    }
17
  }
18
}

Each search result contains the title and url of the page, along with the first 200 characters of its content (body_excerpt). In the highlight attribute you can also find the parts of the title/page content that match the query, with the specific occurrence of the query highlighted in a [h] tag.

You can easily replace the [h] tag with a proper HTML tag of your choice like this:

1
function highlightMatches(string, highlight) {
2
  return string.replace(/\[h\](.+?)\[\/h\]/g, function(a, b) {
3
    var div = document.createElement('div');
4
    div.innerHTML = highlight;
5
    div.children[0].innerText = b;
6
    return div.children[0].outerHTML;
7
  });
8
}
9

10
highlightMatches('[h]Florence[/h] Apartments for Rent', '<span class="highlight"></span>');
11
// -> '<span class="highlight">Florence</span> Apartments for Rent'