Proposal: add browser.search.getSuggestions method

[NV]

There's a browser.search API that allows opening a page with search results using the browser default search engine. However, there's currently no API to get search suggestions.

Original Proposal

I propose to add browser.search.getSuggestions method:

browser.search.getSuggestions(
  query: SuggesionQueryInfo
): Promise<string>;

interface SuggestionQueryInfo {
    text: string;
    engine?: string;
}

getSuggestions should return the request body as text (example).

Revised proposal

The original proposal doesn't allow to control caching or stopping unfinished requests. If we simply expose the URL of the selected search engine, we can use it with fetch instead.

browser.search.getSuggestionsURL(query: SuggesionQueryInfo): string

interface SuggestionQueryInfo {
    text: string;
    engine?: string;
}

(This could be asynchronous if that makes more sense for the implementors.)

---

Related info:
The suggestion response format: OpenSearch/Extensions/Suggestions/1.1
Real-world example: https://www.google.com/complete/search?client=chrome-omni&q=test

[yankovichv]

Cool idea. But I don't think Google will do that. How do you explain to them the purpose of this API? For what cases?

And since you know the URL of the unofficial API, you can use it without the API.

[NV]

I'm working on an extension that, as one of its features, adds a custom new tab UI with search across history, bookmarks, and, well, the web. Similarly to the existing address bar, it includes search engine suggestions.

Having Google hard-coded isn't great for users that have a different search engine selected in their browser.

When using the "unofficial API", it isn't possibly to provide all the same query parameters as Chrome does in the address bar. Notably {google:sessionToken} and {google:suggestAPIKeyParameter} (Chromium source). These parameters allow to provide personalized suggestions.

While this is a bit out of my depth, I see this API slightly beneficial for Google. Google is by far the most popular default search engine. It likely that the search suggestions would be used in conjunction with browser.search.search, and thus lead to the search results page.

[NV]

To clarify a possible confusion:
I specifically request search engine suggestions. Not everything-in-the-address-bar's-suggest-box API, which includes open tabs, history, etc. These are already available through other APIs.

[oliverdunk]

Just following up from the meeting. I think ultimately the thing I wanted to confirm was if you were happy with browser.search.search returning fully anonymous, generic results.

From the meeting it sounded like this was ok, but in the previous comment you said:

When using the "unofficial API", it isn't possibly to provide all the same query parameters as Chrome does in the address bar. Notably {google:sessionToken} and {google:suggestAPIKeyParameter} (Chromium source). These parameters allow to provide personalized suggestions.

If there is any desire for personalisation it feels like this then becomes a higher-risk API that may need more permissions.

[NV]

@oliverdunk that's a good question. The generic results are good enough for most cases, in my experience.

[yankovichv]

@NV, our experiments show that the Google Suggestions API returns personalized results without the parameters you specify. Enough user cookies.

@oliverdunk, сould you elaborate more on how to get search suggestions using browser.search.search? I studied the Chrome documentation (https://developer.chrome.com/docs/extensions/reference/search/) and experimented, but I did not understand how this API is related to hints.

[NV]

@yankovichv it wouldn't send cookies either (assuming that we converge on fully anonymous, generic results).

[NV]

I mocked my initially proposed API I proposed and quickly found it quite inflexible. For instance, I wanted to force-cache (as in fetch), and I couldn't. I added a revised proposal.