You can define fields with custom names and values using meta tags on your web pages. The search API returns the names and values of the custom fields in search results, and you can filter the search results using them.

Supported length, characters and types of custom fields

The maximum length of the custom field name is 256 characters. Please note that custom fields’ names may contain only the following characters:
[a-zA-Z0-9_-]
Additionally, the URL-encoded values of custom fields may only contain US ASCII characters (octets 0 – 127) except control characters or delimiters: ( "(" | ")" | "<" | ">" | "@" | "," | ";" | ":" | "\" | <"> | "/" | "[" | "]" | "?" | "=" | "{" | "}"
| SPACE | TAB ).

Custom fields support the following data types:

  • keyword: Default data type. It cannot be searched but can be used as filters.
  • text: Can be both searched and used as filters.
  • integer: Can be used with range filters.
  • double: Use point as decimal separator. Example: “5.74”. It can be used with range filters.
  • date: Holds date, time and time zone. It should be in ISO 8601 format. The time part is optional.
    Examples: “2019-11-19T00:00:00.000Z”, “2019-11-19”. Can be used with range filters.

For a specific custom field name, the data type will be locked after the first time the field is encountered by our crawler. Because of this, the data type of a custom field can not be changed at a later date. If you need to do this, change the name of the field as well. A custom field meta tag with an unrecognized data type value will be ignored.

Defining custom fields with meta tags

To define custom fields on a web page, use addsearch-custom-field meta tag as follows:

<html>
  <head>
    <meta name="description" content="This is a test page"/>
    <meta name="addsearch-custom-field" content="city=London"/>
    <meta name="addsearch-custom-field" content="genre=rock;genre=pop"/>
    <meta name="addsearch-custom-field" content="genre=hiphop"/>
    <meta name="addsearch-custom-field" data-type="text" content="description=This is a rock/pop event taking place in London"/>
    <meta name="addsearch-custom-field" data-type="date" content="event_date=2019-11-19"/>
    <meta name="addsearch-custom-field" data-type="integer" content="price_cents=599"/>
    <meta name="addsearch-custom-field" data-type="double" content="average_review=4.3"/>
  </head>
  <body>
    Lorem ipsum
  </body>
</html>

You can assign multiple values to a single custom field name. Add multiple values to separate meta tags or combine multiple values by separating them with a semicolon.

Search results can be filtered against custom fields in the Search API and Separate results page.

Defining Custom Fields with HTTP Headers

In addition to meta tags, custom fields can be defined with HTTP headers. To define a custom field with an HTTP header, use the header Addsearch-Custom-Field.

For example:

Addsearch-Custom-Field: genre:keyword=Rock%20%26%20Roll
Addsearch-Custom-Field: genre=Rock%20%26%20Roll

Custom fields can also be combined in the same header:

Addsearch-Custom-Field: genre=Rock%20%26%20Roll, genre=Pop,
band:keyword=Wham%21

Or in multiple headers:

Addsearch-Custom-Field: genre=Rock%20%26%20Roll, genre=Pop
Addsearch-Custom-Field: band:keyword=Wham%21

Additional resources

Was this helpful?

Need more help?

We’re always happy to help with code or other questions you might have. Search our documentation, contact support, or connect with our sales team.