docs(specs): Review OpenAPI Analytics (search analytics)

[gazconroy]

This is one of several PRs addressing the Analytics API.

This PR reviews just the search operations of the Analytics API.

🧭 What and Why

Questions and notes

In the docs, there are 15 API calls. In the OAS, just 12. Should the missing calls be added to the OAS?

getTopSearches

• In the response, count is always (much) smaller than nbHits (whatever the setting of clickAnalytics). This doesn’t seem intuitive. What’s the difference between count and nbHits?
• Response has a clickPositions object which isn’t defined in the OAS

getSearchesCountResponse

• Response has a withFilterCount field in the searches object which isn’t defined in the OAS

getNoResultsRate

• In the response, what is noResultCount? I’ve put in the placeholder “Number of occurrences” but that's not very helpful
• In the response, noClickCount is defined as “Number of click events.” This doesn’t seem to be correct in this context
  getTopHits

getTopHits

• I’ve changed the description to “Returns the most popular clicked results in the latest 1,000 searches.” Is this accurate?

getTopFilterAttributes/getTopFilterForAttribute/getTopFiltersNoResults

• Does this apply to the “1,000 most used filters” (for all time?) or the “1,000 most recently used filters”. I’m assuming the latter but the former is the original wording

getTopFilterForAttribute

• In the response API calls I made, operator is returned as :. What does that indicate? What are the potential settings for operator?

getTopFiltersNoResults

• I’ve written “Returns top filters for filter-enabled searches that don’t return results.” Is that correct, though?
• If I don't specify search in the call, I’d either expect a large number of returned values (for all “no result” searches) or an error message saying search is necessary. Instead, I get {"values": null}

getTopCountries

• What does this do? Is this related to geo searching? To cluster location? To user IP address country correlation?
• The description says “Returns top countries. Limited to the 1,000 most frequent ones.” Most frequent country?
• Are there any prerequisites for this to work? When I make a call, I get {"values": null}

🎟 JIRA Ticket: DOC-1112

Changes included:

Changes to summary, description and examples

🧪 Test

[netlify]

✅ Deploy Preview for api-clients-automation ready!

Name	Link
🔨 Latest commit	f41adb3
🔍 Latest deploy log	https://app.netlify.com/sites/api-clients-automation/deploys/64b5242fd4db590008eb8ba9
😎 Deploy Preview	https://deploy-preview-1689--api-clients-automation.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify site configuration.

[algolia-bot]

✗ The generated branch has been deleted.

If the PR has been merged, you can check the generated code on the main branch.
You can still access the code generated on main via this commit.

[kai687]

Good for final review by API clients team

[shortcuts]

awesome!