Search and trending

Two endpoints help you build a search box: search finds games by what a person types, and trending lists the words people have been searching for lately.

Search

GET /catalog/search matches the start of a title word, a tag or a creator’s name, and returns game cards with the best match first.

curl -s "https://bazoodle.com/api/v1/catalog/search?q=coin"

Parameter	Meaning
`q`	The search text. Up to 80 characters; only the first four words are used.
`limit`, `offset`	Paging, as in Paging through lists.
`record`	Leave it out. `record=1` is only for Bazoodle’s own search box: see below.

How matching works

Every word in q has to match the start of a word in the game’s title, the start of one of its tags, or the start of the creator’s name. So coi finds “Coin Grab”, and party coin finds party games with a title word starting “coin”. Matching ignores case. Results are ordered by how good the match is (the title equal to your text first, then titles that start with it, then the other matches), and by rating after that.

Response

{
  "query": "coin",
  "games": [ ...game cards... ],
  "next_offset": null,
  "recorded": false
}

Field	Type	Meaning
`query`	string	The text that was searched, cleaned up. Empty if `q` was missing or too long.
`games`	list of game cards	The matches. Empty when nothing matches.
`next_offset`	number or `null`	The next page, or `null`.
`recorded`	boolean	`true` only if the search was counted for trending searches.

A missing, empty or longer-than-80-characters q is not an error: you get 200 with no games.
Search covers only kid-friendly public games and never tells you that a hidden game exists.
Search has its own rate limit group. Wait until the person stops typing before you call it.
Cached for 15 seconds.

GET /catalog/search/trending returns the words people have been searching for lately. Use it to suggest searches in an empty search box.

curl -s "https://bazoodle.com/api/v1/catalog/search/trending"

There are no parameters. The response has at most 8 entries, most searched first, and is often empty on a new or quiet site:

{
  "terms": [
    {"rank": 1, "term": "coin"},
    {"rank": 2, "term": "party"}
  ]
}

Field	Type	Meaning
`terms[].rank`	number	1 for the most searched.
`terms[].term`	string	The word, lower case.

There are no counts in the response, on purpose.

What is counted, and what is not

Trending searches are designed so they cannot reveal anything about a person:

A search is counted only when the website sends record=1, and only if the text is exactly a real catalogue word: a whole word of a game title, a full title, or a tag. A name or sentence someone typed is never stored.
Counts are kept per day and never tied to who searched. Recent searches stay on the person’s own device, never on the server.
A word has to be searched several times within two days before it can appear.
Counts are split by the strictest tier of the results the searcher saw, so a word that only mature games explain can never be suggested to a child.

Cached for a minute (Cache-Control: private, max-age=60). An empty terms list is normal.