Field notes on the Qloo API. What building Hearsay taught me, written for the people who make it. Each note says how to reproduce it and what Hearsay does about it.

First, what worked well: one call scores any list of entities against any taste, across categories (a game against artists, a football club against TV shows). Cross category affinity is the whole reason Hearsay can exist. Search with a type filter resolves names reliably, and latency stayed under a second for most calls.

1. Affinity scores need a per query reference point

   The docs describe 0.6 to 0.8 as high relevance. For fans of Grand Theft Auto, The Wiggles scores 0.70, Michael Bublé 0.76 and Enya 0.76, while Papa Roach scores 0.97. For Taylor Swift fans, Celine Dion scores 0.91. Read alone, almost any famous name looks relevant.

   ReproduceGET /v2/insights?filter.type=urn:entity:artist&signal.interests.entities=<GTA id>&filter.results.entities=<The Wiggles id>,<Papa Roach id>

   What Hearsay does Hearsay scores five famous unrelated picks with every check and judges each pick against the middle one, plus the seed's own top 50.

2. Scoring chosen entities returns 20 results unless take is set

   filter.results.entities with 27 ids returned 20 entities and dropped the lowest scores without saying so. With take=27 all 27 came back.

   ReproduceGET /v2/insights?filter.type=urn:entity:artist&signal.interests.entities=<id>&filter.results.entities=<27 ids> (then add take=27)

   What Hearsay does Every scoring call sends take equal to the number of ids.

3. The developer guide says video_game, the server wants videogame

   filter.type=urn:entity:video_game returns 400. urn:entity:videogame works.

   ReproduceGET /v2/insights?filter.type=urn:entity:video_game&signal.interests.entities=<id>

   What Hearsay does Hearsay uses urn:entity:videogame.

4. Scoring one entity inside a location comes back empty

   signal.location.query=Manchester with filter.results.entities=<Oasis id> returns an empty list, for Manchester and for Los Angeles. Location as a signal on its own works well (Manchester gives Liam Gallagher, Noel Gallagher, Lily Allen).

   ReproduceGET /v2/insights?filter.type=urn:entity:artist&signal.location.query=Manchester&filter.results.entities=<Oasis id>

   What Hearsay does Location claims ("big in Manchester") are left out and marked can't check.

5. Heatmap boundary values differ from the docs, and locality returns 500

   The docs list city and neighborhood. The server accepts urn:geohash and urn:entity:locality, and urn:entity:locality returned 500 System Error.

   ReproduceGET /v2/insights?filter.type=urn:heatmap&filter.location.query=London&output.heatmap.boundary=urn:entity:locality

   What Hearsay does Heatmaps aren't used in Hearsay yet.

6. Some audience slices look skewed

   For the 55 and older bucket, ABBA, Adele and UB40 came back negative, and Midsomer Murders and Vera came back negative for older men. Book audiences lean young adult (Doctor Who fans' top books are Heartstopper titles). For Chelsea F.C. fans, an artist entity called "Drake&Orson" ranks first.

   ReproduceGET /v2/insights?filter.type=urn:demographics&signal.interests.entities=<ABBA id>

   What Hearsay does Age group claims aren't checked, book picks are marked low trust, and the method page says so.

7. Rate limit headers are useful, and worth documenting

   Every response carries x-second-ratelimit-* and x-month-ratelimit-* headers (5 per second, 10,000 a month on the hackathon key). They made it easy to build a budget guard, but I only found them by reading raw responses.

   ReproduceAny request; look at the response headers.

   What Hearsay does Hearsay reads x-month-ratelimit-remaining on every call and stops live checks before the month runs out, keeping cached results available.

Tested against hackathon.api.qloo.com between 13 and 15 October 2026. Results can change as the API changes.