Skip to main content

Searching Entities

The Gateway provides a search endpoint that allows you to search for entities.
Here is a basic request example:

POST 
/api/v1/entities/search
{
    "filter": {
        "type": "filter-link",
        "content": "/"
    },
    "result": {
        "format": "json"
    },
    "options": {
        "page": 1,
        "size": 25
    }
}

Once your search query has been processed, the system will return all entities that match your filter, in the format you requested. The response includes not only the actual entities but also additional metadata (meta) that provides context about the query results — such as processing total number of hits and pagination details.
This helps you understand the scope of the data returned and makes it easier to handle larger result sets programmatically.

{
  "status": "success",
  "meta": {
    "took": 23, // time the execution took in ms
    "total": 100, // total number of entities found
    "pagination": {
      "size": 25, // number of entities per page
      "page": 1, // current page
      "pages": 4 // total number of pages based on the total number of entities and the size
    }
  },
  "data": [ // array of result entities
    {
      "_id": "6798b7b709256629566d21bd",
      "types": [
        "schema:Event",
        "schema:Trip"
      ],
      "types_all": [
        "schema:Event",
        "schema:Trip",
        "schema:Thing",
        "schema:Intangible"
      ],
      "schema:name": [
          {
            "value": "Event Name",
            "lang": "en"
          }
      ]
    },
    ...
  ]
}
info

The result can contain pseudo fields like pseudo:linkedEntities or pseudo:timeline.
Have a look at Pseudo Fields to understand what they are and how to use them.

warning

If you are not getting any results or not what you are expecting. But are 100% sure that there are entities that match your filter,
please check the following:

  • Is your filter correct? (e.g. does it match the entities you expect?)
  • When you are using a project/channels filter, is the project and/or channel correct?
  • Are the entities expired? (The case for Events that are in the past) (showExpired)
  • Do the entities you expect count as hidden entities? (ContactPoints, Accommodations, etc.) (showHidden)
  • Have the entities possibly been deleted? (showDeleted)

If you are still not getting the expected results, please contact us.

Filter​

The 'filter' object is used to specify the search query.
The 'type' field specifies the type of filter. The 'content' field specifies the filter content.

Possible filter types:​

"filter-link" Filter by a filter link. This variant is also allowed without authentication. But you need to prefix your filter-link with the desired project and channel. (i.e. /projects=1234/channels=5678/...).

"dsl" Filter by a native Elasticsearch DSL query. This option allows for more complex queries. You always need to be authenticated to use this filter type.

Result (result)​

The result specifies how the search result should be formatted and which properties should or must be included in the result.

Format (format)​

The format field specifies the format of the result.
Possible formats are:

"json" (default) Return the result as a JSON object.

"geo_json" Return the result as a GeoJSON.

info
  • The geo_json format automatically applies filters to ensure that only geo-located entities will be returned.
  • The geo_json format is limited to maximum 50 entities per request.

"gpx" Return the result as a GPX File.

info
  • The gpx format automatically applies filters to ensure that only geo-located entities will be returned.
  • The gpx format is limited to maximum 10 entities per gpx file.

"elasticsearch" Return the result as a raw Elasticsearch response.

Properties (properties)​

The properties that should be included in the result.
If the properties field is not set, all properties will be included in the result.

Includes (includes)​

The includes field specifies the fields that the entity MUST have, entities that don't have the specified properties are not returned.

Options (options)​

The options specify additional options for the search query.

"page": number (default: 1)
The page number of the result.

"from": number (default: 0)
The starting point of the result. (Ignored if page is set)

"size": number (default: 25)
The number of entities per page.

"trackTotalHits": boolean (default: false)
There is a technical limitation in Elasticsearch that prevents the total number of hits from being calculated above 10000. If you have more results and need to know the exact total, you can set this option to true. It will bypass this limitation but also increase the response time.

"strict": boolean (default: false)
If set to true, the search will only return entities with the fields specified in the result properties.

"showDeleted": boolean (default: false)
If true also deleted entities will be returned.

"showExpired": boolean (default: false)
If true also expired entities will be returned.

"excludeSharded": boolean (default: false)
If true, sharded entities will be excluded from the result.

"showHidden": boolean (default: false)
If set to true, hidden entities will be included in the result. Hidden entities are entities that are usually not needed in a standard result query. (like standalone ContactPoints or Accommodations)