How to highlight matching terms in search results#

The APITube News API hl parameter returns short text snippets with your search terms wrapped in highlight tags, so you can show users exactly why each article matched. Add hl=true to a keyword search and the response gains a highlighting object: each matching article gets arrays of snippets where every hit is surrounded by <em> and </em> by default.

curl "https://api.apitube.io/v1/news/everything?title=bitcoin&hl=true&api_key=YOUR_API_KEY"

You can send the key as a header (X-API-Key: YOUR_API_KEY) instead of the api_key query parameter. Highlighting reuses the terms from your search, so it only works when you actually searched for something — it has no terms to mark on an unfiltered request.

How does highlighting work in the News API?#

Highlighting is enabled with hl=true (or hl=1). The terms it marks come from your title (or search) keywords, so title=bitcoin&hl=true highlights “bitcoin” wherever it appears in the chosen fields. For each article that contains a match, the API extracts a snippet of surrounding text, wraps each hit in the highlight tags, and adds it to a top-level highlighting object keyed by article ID.

{
  "status": "ok",
  "results": [...],
  "highlighting": {
    "12345": {
      "title": [ "Breaking: <em>Bitcoin</em> reaches new all-time high" ],
      "description": [ "...The price of <em>Bitcoin</em> surged past $100,000 today..." ]
    }
  }
}

Each field holds an array of snippets, and snippets taken from the middle of a longer text are wrapped with ... on both sides to show they are an excerpt. If no article matches, the highlighting object is left out of the response entirely.

Which fields can you highlight?#

Use hl.fl to choose which fields are scanned for matches. It accepts a comma-separated list of up to 5 fields, and the allowed values are title, description and body. If you do not set hl.fl, the API highlights title and description by default.

curl "https://api.apitube.io/v1/news/everything?title=artificial intelligence&hl=true&hl.fl=title,description,body&api_key=YOUR_API_KEY"

Adding body is the most useful change: it surfaces snippets from deep inside the full article text, which is where the richest context usually lives. Naming a field that is not title, description or body returns 400 with error ER0322, and the message lists the allowed fields.

How to control snippet size and count#

Two parameters shape the snippets themselves:

• hl.fragsize — the maximum length of each snippet in characters. Default is 150; values are clamped to the 50–500 range.
• hl.snippets — the maximum number of snippets returned per field. Default is 3; values are clamped to the 1–10 range.

curl "https://api.apitube.io/v1/news/everything?title=climate change&hl=true&hl.fragsize=300&hl.snippets=5&api_key=YOUR_API_KEY"

Larger hl.fragsize gives more surrounding context per match, while a higher hl.snippets returns more separate excerpts from the same field — handy when a term appears several times in a long body.

How to change the highlight tags#

By default matches are wrapped in <em> … </em>. Override both sides with hl.tag.pre and hl.tag.post to fit your front end — for example a styled <mark> element or a custom span.

curl "https://api.apitube.io/v1/news/everything?title=bitcoin&hl=true&hl.tag.pre=<mark>&hl.tag.post=</mark>&api_key=YOUR_API_KEY"

This lets you drop the snippets straight into your UI without a find-and-replace pass on the response. If you only set one of the two tags, the other keeps its default.

Does highlighting match word variations?#

Yes. Before marking matches, the API expands each search term using its synonym and morphology dictionaries, so a search for “run” also highlights “running”, “runner” and “ran”. The expansion is language-aware, which means variations are caught across the languages APITube indexes — not just English. This is why a snippet can show highlighted words that are not letter-for-letter identical to what you typed.

Common Questions#

Which endpoints support highlighting?#

Highlighting works on the search and listing endpoints: /v1/news/everything, /v1/news/top-headlines, /v1/news/story, /v1/news/category, /v1/news/topic, /v1/news/industry and /v1/news/entity. The hl parameters behave the same on each one. Pair highlighting with field selection to keep responses lean while still returning the snippets you need.

Why is the highlighting object empty or missing?#

Highlighting needs search terms and at least one match. If you send hl=true without a title (or search) keyword, there is nothing to highlight and the highlighting object is omitted. The same happens when none of your results actually contain the term in the highlighted fields. Single-character terms are also skipped — a term must be at least two characters long to be highlighted.

What errors can highlighting return?#

All highlighting errors are 400 responses. ER0320 is returned when hl.fl is empty while hl=true, ER0321 when hl.fl lists more than 5 fields, and ER0322 when a field name is not title, description or body. Send a short, valid hl.fl list — or omit it to use the title,description default — and you will not hit any of them. The full parameter list is in the official News API parameters reference.

Does highlighting cost an extra request?#

No. Highlighting is computed inside the same search call and returned in the same response, so it is billed as the one request you already made — there is no separate charge for adding hl parameters. It pairs naturally with faceting, which also rides along on the same request to enrich a single search response.