Competiscan

Find out what to send — the archive's own vocabulary, read live. Call this before putting a name you are unsure of into search_campaigns, and especially before putting one into advanced_filters. Values here are read from the archive itself, so they are always what the search endpoints will accept. Four modes, resolved in this order: 1. field (+ query) → search one filter's vocabulary. For the ones too large to list: company (187,025 names), affinity_name (11,427), publication (998), dma (210), utility (32). Prefix matches come first. 2. parent → walk the taxonomy one level at a time. parent="Credit Cards" lists what sits under that sector; pass one of those names back to go a level deeper, down to four levels. Only nodes PowerSearch actually offers are returned, so anything that comes back is a selection search_campaigns will accept. 3. group → the enhanced filters in one group and their accepted values. Groups: demographics (7 filters), mortgage (8), campaign_flags (15), energy (4), channel_delivery (8), other (5), card_offer (13), messaging (6), geography (2). Pass "all" for every group at once. 4. nothing → every value the core filters accept: the 17 sectors, 10 media channels, 5 audiences, country, date_field, and the arity limits on company, entry_id and ocr_text.

discover_filters

The thumbnail image of one archive piece, by entry_id. This is the show_pieces viewer's image source and returns nothing but the picture. To find out what a piece says, use read_piece.

get_piece_thumbnail

Read the words printed on specific pieces, by entry_id. The exact inverse of search_campaigns' ocr_text filter: that one asks "which pieces contain these words" and never returns text; this one asks "what does this piece say". Most real work needs both, in that order — search first, read second. Reading a piece displays nothing to the user. show_pieces is what puts a piece in front of them. THE TEXT HAS NO PUNCTUATION. The OCR pipeline normalises to words and spaces, so a piece printed "pre-approved" reads back as "pre approved" and "0.36% APR" reads back as "0 36 APR". Reading a piece is the fastest way to work out why an ocr_text search missed it. There is no batch endpoint; this loops one keyed lookup per id, which costs exactly what a batch would.

read_piece

Search the Competiscan archive. This is the only search tool — every filter the archive supports is reachable from here. AT LEAST ONE NARROWING FILTER IS REQUIRED: sector, category, media_channel, audience, company, panelist_id, entry_id, or a date bound. country and ocr_text narrow a result set but cannot define one. VALUES OR, FIELDS AND. media_channel=["Direct Mail","Email"] with audience=["Consumer"] means "direct mail or email, AND to consumers". Every filter takes names or numeric ids; names are preferred and matching ignores case and surrounding whitespace. An unknown value is a 400 listing what is valid — never a silently empty result.

search_campaigns

Display archive pieces to the user as visual cards, by entry_id. Each card shows the piece's thumbnail, product name, media channel, date and headline, with a button that opens its PDF. This is the only tool that displays anything: search_campaigns and read_piece return data to the model alone. Use it when the user asks to see pieces, or to show the specific piece an answer cites as its example or recommends looking at. A piece does not have to be read first — an entry_id from search_campaigns is enough. Each call draws its cards at that point in the reply. A reply can show all of its pieces in one call, or call this once per section to put a piece's card beside the text about it.

show_pieces