Search Guideedit

Searching is how you read data and generate results from the documents stored within your Engines.

The search endpoint will be invoked each time a search is performed by a user.

Unlike the other endpoints, which customize Engines, view analytics, tune relevance, or index documents, search is for, well... Searching!

You can use your Public Search Key or your Private API Key to query the search endpoint. The Public Search Key is for performing search using client side JavaScript, within mobile application development, or any other context where you are at risk of exposing your API Key.

The Public Search Key key begins with: search-. The responses generated by the search endpoint should contain data from your engines that you want your users to see. That is why it has its own special, public key.

Or, instead read the Search API Reference to get coding.

What do I search?edit

Search is all about finding documents.

A document is an individual JSON object.

When you add data into your Engines, you are taking database or backend API objects and indexing them.

But what does it mean, to index?

To better understand this, we will look no further than a JSON object:

  "name": "SuperObject",
  "authors": "Examplio McDemonstratio",
  "downloads": "98765",
  "info": "A stunning look at potential."

That is one object. Your datastore will likely contain many.

During indexing, your set of objects, of documents, is evaluated to develop a schema.

The keys are translated into Fields.

The values are, by default, given the type of text.

Prior to your data being indexed, the schema is created:

Existing Field Type









Each document that you index can now be considered part of a set of data.

This changes the objects in a small way:

  "id": "1234",
  "name": "SuperObject",
  "authors": "Examplio McDemonstrate",
  "downloads": "98765",
  "info": "A stunning look at potential."

Each one now contains an id, this id is how your documents are known to your Engines.

By belonging to a defined - though still flexible - schema, the Engine can get deep into its analysis of the documents.

The end result is the ability to search vast sets of objects, of documents, with great precision.

How do I search?edit

If you are the visitor, then you arrive at an application, seek out the search bar or search box, or magic box, enter some text, then hit enter. If search is fast and relevant, then they click on a result, their experience continues and they consume the content, purchase the project, or accomplish whatever it was they sent out to do.

If you are the developer, then you develop applications that access a robust set of APIs. You can access the APIs via an official client, like Python, Ruby, JavaScript, NodeJS, or Java. Or, you can weave in whatever sort of programmatic brilliance that you can dream up.

The visitor has it easy.

They are not aware of the deep logic that is happening below the interface with which they interact.

The act of searching, in its most simple form, is a request against an Engine wherein the document they seek is indexed.

Example - Performing a simple search.

curl -X POST '' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer search-qcqrj73hmom796c98r22zeao' \
-d '{
  "query": "search"

It is a big difference between returning something and returning the right thing.

The name of the game is relevance.

When we make a request, the Engine will send a response object in return.

The response object contains a nested _meta object with a score key.

The value of the score key is the relevance.

Consider that we host an application for finding useful RubyGems.

The best search Gem of all - somehow, even better than App Search - is Searcheror Supreme.

It is popular.

If we had basic search, a visitor querying for search would return Searcheror Supreme as one of the last results.

That can lead to a poor experience - we want them to find the best Gem for their query.

The result of the search query would be:

   "name": {
     "raw": "Searcheror Supreme"
   "id": {
     "raw": "1334"
   "authors": {
     "raw": "Doctor Odd"
   "downloads": {
     "raw": "421321431"
   "info": {
     "raw": "A mind-bending experience of reclamation from the Ether. Not compatible with Dormammu Exiler."
   "_meta": {
     "score": 4.986149

The relevance score under the _meta key is so low, a mere 5! Why is that?

By default, the Engine would take a uniform look across all fields for the keyword sent along with the query.

The word search appears only once, as a part of the name Searcheror.

Despite being the most popular and relevant Gem, it is buried under results that use the word search more often.

This is not ideal! But this is how most search functions work.

To go deeper, you must write sophisticated algorithms.

You would need to solve challenging data structure problems.

But you already have a million things to build.

Managing these deep search complexities is the problem solved by App Search.

There are many different endpoints to help you craft a fast, imaginative and useful search experience.

Explore the documentation to learn more.

What about result meta data?edit

The meta key will be a JSON object containing information about the result set, such as:

  • request_id: A unique id that coincides with each request. Each API request is logged within the API Log. The unique id will help you analyze requests.
  • warnings: As long as a request is formatted in the proper way, a status code of 200 will be returned. Warnings will inform you of issues within your queries.
  • alerts: Similar to warnings, alerts inform you of issues with your service.
  • page: Has four potential arguments...
Page Argument Detail


Page number that is in the results field.


Number of of results available.


Number of results that match the query.


Number of results per page.

Why search?edit

The Internet offers information.

A product, a thought — whatever it may be, search can get people to the things they want, quicker.

The faster they get there, the more likely they are to have an enjoyable experience and help you accomplish your business goals.

Where next?edit

You are now familiar with the basics of search. Next, you can apply powerful tools to provide a relevant and valuable search experience. If you want to start polishing up how results appear, improving relevance and meeting business goals in the process, consider reading about Curations and Relevance Tuning. If you want to see how your users search, dive into Analytics. For the nitty-gritty details on the Search API, we have the Search API Reference.