Search parameters
You can use a variety of query parameters to search and filter items in the response from any collection endpoint including entries, content types and assets.
Content type
To search for entries with a specific content type, set the content_type URI query parameter to the ID you want to search for.
Note: When querying entries and using search filters based on fields or ordering by fields you must specify this parameter. You can only specify one value for content_type at a time.
Use the Get all entries of a Space endpoint, see example:
content_type is a string representing the alphanumeric id of the content type to retrieve. This example finds all entries of content type ‘Product’.
Select operator
The select operator allows you to choose what fields to return from an entity. You can choose multiple values by combining comma separated operators.
For example, if you want to return the sys.id and fields.name of an Entry you would use:
You can fetch the entire sys or fields object and it’s sub-fields by passing it to the select operator. For example to omit the sys object:
The select operator has some restrictions:
- It is only applicable for collections of Entries and Assets, and with an Entry you must provide the
content_typequery parameter. - It can only select properties to a depth of 2. For example,
select=fields.productName.en-USis not valid. - If you want to select a property for a specific locale, you need to combine the
selectandlocaleoperators, e.g/assets/?select=fields.productName&locale=en-US. - You can select up to 100 properties.
- If you use the select operator on an Entry with linked fields, only the content linked to a field you select will be returned.
If you provide an invalid property path, e.g fields.doesNotExist, Contentful returns a 400 Bad request containing the invalid property path.
Use the Get all entries of a Space endpoint, see example:
To select only the productName field of each entry.
Equality operator
You can search for exact matches by using the equality operator. This includes querying an entry by an ID value instead of retrieving the Entry directly, which allows you to include resolved links.
Note: Equality and inequality operators are not supported for text fields and you need to constrain search queries for fields with a content_type URI query parameter.
Use the Get all entries of a Space endpoint, see example:
To find all entries with the ID <entry_id> (IDs are unique).
Inequality operator
Uses the [ne] parameter to exclude items matching a certain pattern.
Use the Get all entries of a Space endpoint, see example:
To return all entries, except those with the ID <entry_id>.
Array equality/inequality
The equality/inequality operators also work with array fields:
- Equality: If one of the items in an array matches the searched term, then it returns the entry.
- Inequality: If one of the fields in an array matches the searched term, then the entry is not returned.
Note: As the query filters by a field, you need to specify a content type.
Use the Get all entries of a Space endpoint, see example:
This example finds all products tagged as accessories by matching fields.tags (an array) against a single value.
Array with multiple values
It’s possible to use the [all] operator to retrieve entries matching a specific set of values (e.g. fields.likes[all]=flowers,accessories)
Use the Get all entries of a Space endpoint, see example:
To find all products tagged as flowers and accessories by using the all operator with fields.tags (an array) and the two values.
Inclusion
You can filter a field by multiple values with the [in] operator. When applied to an array value there must be at least one matching item. Similarly, when including a field value, you need to specify a Content type.
Use the Get all entries of a Space endpoint, see example:
To retrieve entries that match accessories and flowers.
Exclusion
You can filter a field by multiple values with the [nin] operator. When applied to an array value there must be at least one not matching item. Similarly, when including a field value, you need to specify a content type.
Use the Get all entries of a Space endpoint, see example:
To retrieve all products tagged as neither ‘flowers’ nor ‘accessories’.
Existence
You can check for the presence of a field using the [exists] operator. It checks whether a certain field is defined (i.e. it has any value) or not.
If the field is not defined, it will not be present in the JSON payload and the operator will consider it non-existent.
You can pass true or false as a parameter depending on if you want to retrieve entries where the field exists (true) or does not exist (false). Please note that the parameter is case sensitive, True or False are not valid values.
Use the Get all entries of a Space endpoint, see example:
To retrieve all entries that have a value for field.tags defined.
Ranges
Four range operators are available that you can apply to date and number fields:
[lt]: Less than.[lte]: Less than or equal to.[gt]: Greater than.[gte]: Greater than or equal to.
When applied to field values, you must specify the content type in the query.
Use the Get all entries of a Space endpoint, see example:
To retrieve entries updated since midnight of January 1st 2013.
Full-text search
You have available two flavours of full-text search:
- Global, described in this section
- Field scoped, described in the section full-text search on a field
How does global full text search work
There are cases where you want to find all the content resources which contain some particular words (search terms) but you don’t know from which content type (for entries) or on which field those terms can be, so you can’t use any of the field filters. For cases like these full-text search is the perfect tool for the job. With it you can find all the content resources which match your search terms in any of their text and symbol fields.
Full-text search can be used to find entries, assets or content types. For the remainder of this section we will refer to entries but the same principles and restrictions will apply to the other types.
Which content is looked up during a global full-text search?
All text (both regular and rich text) and symbol fields in all the locales in your environment will be looked up when doing a global full-text search.
How is an entry considered a match?
Before we explain how we identify matches to your search terms we have to explain how these terms are transformed before they are sent to the search engine. After the API has received your query, the input string is sanitized (i.e. some special characters are removed), tokenized (i.e. split into it’s constituent parts) and normalized (i.e. guarantee that the tokens satisfy certain constrains, e.g. removing XML tags). Then each of the remaining search tokens is suffixed with a wildcard operator, which implies that full-text search at contentful is left-anchored.
When checking if an entry satisfies the search criteria, the search engine tests if all of the search tokens (i.e. the transformed search terms) can be found in any field in any locale in the entry. This means that an entry can be included in the result set due to matches in different fields and different locales or due to a match in just one field in just one locale. There is also no guarantee about the order in which the search terms can appear in the matching entries. A search for modern red house can be matched with entries which have those words in any possible order (e.g. red … house … modern, red … modern … house, etc.).
All this combined means that when you for example search for my cat is blue, the search engine will find all the entries where there are words starting with my and cat and is and blue:
- A field with content like my cat is blue will match.
- A field with content like my cat is red will not match.
- A field with content like there is a catastrophic blueberries accident in my town will match.
- A field with content like there is a caterpillar in my house will not match.
- A field with content like this is a picture of a caterpillar and myself wearing a bluejacket will match.
- A field with content like my cat is <b>blue</b> will match.
- A field with content like my cat is <b class=“blue”>great</b> will not match.
- An entry with a field with content like my house was blue and another field with content like there is a cat will match.
Check below the phrase full-text search section if you are interested on those entries where the given search terms can only be found in one field and in the same order as in the search input.
Check the full-text search on a field section if you are interested only on those entries where the given search terms are in only one field.
Phrase full-text search
By default full-text search queries will take the search tokens and find all those entries where the tokens can be found in any field, in any locale and in any order. There are however cases where you might need a more restrictive search strategy and only get those entries where the matches are in the same order as you specificed in the search and in only one field. To achieve this you can wrap the search terms in double quotes (”) to enable phrase search.
When you for example search for “my cat is blue”, the search engine will find all the entries where the words my, cat, is and blue are found in that order in one field:
- A field with content like my cat is blue will match.
- A field with content like my cat is <b>blue</b> will match.
- A field with content like blue is the color of my cat will not match.
- A field with content like my caterpillar is blue will not match.
- An entry with a field with content like my house was blue and another field with content like there is a cat will not match.
If you wish you can combine phrase search with the default full-text search behaviour. This can be useful to refine even more the result set. For example a search like “my cat is blue” summer london will match all those entries where the term “my cat is blue” can be found in just one field in one locale and where the terms summer and london can be found in any field in any locale present in the entry (including the field where the phrase was matched).
Other considerations about full-text search
- Full-text search is case insensitive and might return more results than expected.
- A query will ignore search tokens with less than 2 characters.
- When using full text search, make your search terms as specific as possible.
- The
[match]operator might return better results. - Use phrase search when possible as it has better performance.
- For performance reasons it is recommended to use the equality search operator when searching for slugs or text IDs.
For more tips on using full-text search, see our Help Center article.
Use the Get all entries of a Space endpoint, see example:
To retrieve all entries containing the word ‘design’.
Full-text search on a field
With the [match] operator you can do a full-text search restricted to the
content of a specific field. The way full-text search behaves on one field is
the same as in the global full-text search and the documentation for the global
full-text search also applies
here, with the particularity that matches on other fields of the entries or
assets won’t be considered. As with the global search, you can enabled phrase
search if you wrap the input search terms in double quoutes (”).
Use the Get all entries of a Space endpoint, see example:
To retrieve all entries which contain words starting with ‘content’ in the ‘website’ field.
Location proximity search
You can use a proximity search on location-enabled content to find results in a specified geographical area.
Note: Queries that include exact coordinates can’t take advantage of our caching layer. With many use cases it should be enough to round the coordinates to 3 decimal places (an accuracy of about 300m), 2 decimal places (an accuracy of about 1km) or more to improve your cache hit rates.
Use the Get all entries of a Space endpoint, see example:
A common use case for location search is to search for places close to the user’s current position.
Use the [near] operator to show results closest to a specific map location and order the results by distance.
This will return all entries sorted by distance from the point at latitude=38 and longitude=-122.
Locations in a bounding object
When displaying content on a map it’s more resource efficient to retrieve only content that is in the current visible map area. For these cases, use the within operator.
Similar to the ‘near me’ use case, this lets you search for locations that are within the specific area on the map and can be useful for finding related entries in the vicinity of another entry.
There are two ways to search for nearby locations.
1. Using a bounding rectangle:
To search for locations within a rectangle area object, use the structure field.center[within]=latitude1,longitude1,latitude2,longitude2, where:
latitude1andlongitude1refer to the coordinates of the bottom left corner of the rectangle.latitude2andlongitude2refer to the coordinates of the top right corner of the rectangle.
2. Using a bounding circle:
The structure field.center[within]=latitute,longitude,radius will return entries included in the circle with fields.center of the given latitude, longitude and radius (in km).
Use the Get all entries of a Space endpoint, see example:
To retrieve entries where fields.center is within the rectangle with:
- Bottom left corner: latitude 1, longitude 2.
- Top right corner: latitude 3, longitude 4.
Links to entry
To search for entries which have a field linking to a specific entry, set the links_to_entry URI query parameter to the ID you want to search for.
NOTE: For most use cases it is more performant to query based on a content type’s reference field if the desired content type is known. See Search on references for an example query
Use the Get all entries of a Space endpoint, see example:
Links to asset
To search for entries which have a field linking to a specific asset, set the links_to_asset URI query parameter to the ID you want to search for.
Use the Get all entries of a Space endpoint, see example:
Order
You can order items in the response by specifying the order search parameter. You can use sys properties (such as sys.createdAt) or field values (such as fields.myCustomDateField) for ordering.
Note: You must set the content_type URI query parameter to the ID of the content type you want to filter by. You can only use the following field types with the order parameter:
The following field types do not support the order parameter:
If you don’t pass an explicit order value the returned collection items will be ordered
descending by publication timestamp (sys.updatedAt) and ascending by id
(sys.id). This means that recently published items will appear closer to
the top and for those with the same publication timestamp the order will be
based on the items’ ids.
Use the Get all entries of a Space endpoint, see example:
To retrieve all entries ordered by creation date.
Reverse order
You can reverse the sort order by prefixing the field with a - symbol.
Use the Get all entries of a Space endpoint, see example:
To order results by the time of the last update, newest to oldest.
Order with multiple parameters
You can order items by specifying the order parameter with attributes(attribute, attribute2). Prefix the field with a - sign to reverse the sort order of the attribute.
Use the Get all entries of a Space endpoint, see example:
Limit
You can specify the maximum number of results as a limit search parameter.
Note: The maximum number of entries returned by the API is 1000. The API will throw a BadRequestError for values higher than 1000 and values other than an integer. The default number of entries returned by the API is 100.
Use the Get all entries of a Space endpoint, see example:
To limit results to 3 entries.
Skip
You can specify an offset with the skip search parameter.
Note: The API will throw a BadRequestError for values less than 0 or values other than an integer.
By combining skip and limit you can paginate through results:
Page 1: skip=0, limit=15 Page 2: skip=15, limit=15 Page 3: skip=30, limit=15 etc.
Use the Get all entries of a Space endpoint, see example:
To skip 3 entries.
Filtering assets by MIME type
You can filter assets by their MIME type group by using the mimetype_group query parameter. Valid groups are attachment, plaintext, image, audio, video, richtext, presentation,
spreadsheet, pdfdocument, archive, code and markup. By default, the API will return all assets.
Use the Get all assets of a Space endpoint, see example:
To return only image assets.
Search on references
You can search for entries based on the values of referenced entries.
For example, if you want to find products of a particular brand, you can use search on references to find the products with one API request.
Structure of a query
Here’s how the example above would look as a query:
- First is the
content_typeparameter which you must include when you want to filter based on the values of the fields of entries of a certain content type. - Second is
fields.brand.sys.contentType.sys.id=<brand_content_type_id>which you use to to filter on fields of entries from content type<product_content_type_id>. - Third is
fields.brand.fields.companyName[match]=Lemnoswhich filters entries to those branded as ‘Lemnos’.
fields.brand.You can search on multiple references at once and combine them into one singe API query with a series of field and value pairs.
Available nested filters
You can use the all, in, nin, exists, match, gt, gte,lt, lte, ne, near and within filters when searching on references. The semantics of these filters are the same as when you use them on a non referenced entry.
Restrictions
Searching on references has the following restrictions:
- You can only search on references on fields which link to a single entry. Fields which hold references to many entries or fields with references to assets are not supported.
- The maximum number of reference searches in one query is 2. A larger value will return an error.
Use the Get all entries of a Space endpoint, see example:
This example will return the Lemnos branded products.