Call Trends API from Crystal with HTTP::Client

A Crystal job talks to Trends API with one POST to https://api.trendsapi.ai/api, a Bearer key, and a JSON body that names a mode. There is no official Crystal library. HTTP::Client sends the request. JSON.parse reads the envelope, then parses the body string a second time. Pulled on 2026-10-15, Google Search for crystal scored 33.0 for the week of 2026-10-10, down 21.43% from 42.0. crystal programming scored 4.0, down 84.0% from 25.0. Those two tokens closed 29 points apart. YouTube for crystal scored 43.0, down 2.27% from 44.0. Do not copy bare crystal 33.0 onto a language-adoption alert that only watches the phrase token at 4.0. The same helper that stores those rows also pulls a live Google Trends board; a rank-2 token that weekly Search still printed at 17.0 versus 0.0 is documented in Katie Zacharia live rank versus weekly Search.

How does a Crystal client call Trends API?

POST https://api.trendsapi.ai/api
Authorization: Bearer <api_key>
Content-Type: application/json

{"mode":"get_growth","source":"google search","keyword":"crystal programming","percent_growth":["7D","30D","3M","12M"]}

require "http/client"
require "json"

def post(payload : String) : JSON::Any
  headers = HTTP::Headers{
    "Authorization" => "Bearer #{ENV["TRENDSAPI_API_KEY"]}",
    "Content-Type" => "application/json",
  }
  response = HTTP::Client.post("https://api.trendsapi.ai/api", headers: headers, body: payload)
  envelope = JSON.parse(response.body)
  # body is a JSON string; parse it a second time
  JSON.parse(envelope["body"].as_s)
end

inner = post(%({
  "mode": "get_growth",
  "source": "google search",
  "keyword": "crystal programming",
  "percent_growth": ["7D", "30D", "3M", "12M"]
}))
puts inner

The first mistake most clients make is treating the body field as an object after one parse. It is still a JSON string. HTTP::Client returns the envelope bytes. JSON.parse then parses body a second time. Library docs:

https://crystal-lang.org/api/latest/HTTP/Client.html
https://crystal-lang.org/api/latest/JSON.html

Free tier allows 100 successful requests per month. Only HTTP 200 responses count against quota. Starter is 5,000, Pro is 25,000, Business is 100,000. There is no Crystal-specific source on this API. npm covers npmjs package names. python covers PyPI project names. There is no Shards source. A watchlist that needs Shards download counts has to pull those from somewhere else. A Nim sibling of this helper is on Nim Trends API. A Zig sibling is on Zig Trends API.

What did get_growth return for Crystal language tokens?

get_growth for crystal on google search tips on 2026-10-10. Store the exact strings. The short token, the programming phrase, and the crystal language phrase are different series. Bare shards is not the package manager.

crystal closed at 33.0, down 21.43% from 42.0, with estimated Search volume 512,000 versus 652,000. crystal programming closed at 4.0, down 84.0% from 25.0. Same Saturday tip, same 7D sign, 29 points apart. The phrase token fell harder. crystal language scored 5.0, down 79.17% from 24.0. 3M on that phrase was 5.0 versus 50.0 (-90.0%). 12M was 5.0 versus 24.0 (-79.17%). YTD was 5.0 versus 25.0 (-80.0%). Do not copy the short token 33.0 onto either phrase.

Bare shards scored 28.0, down 12.5% from 32.0. 12M was 28.0 versus 22.0 (+27.27%). YTD was 28.0 versus 26.0 (+7.69%). That is the English-noun series, not Shards download volume. There is no Shards source. A job that alerts "Shards is down 12.5%" off Search 28.0 is reading a different series.

zig programming scored 19.0, down 9.52% from 21.0. 12M was 19.0 versus 37.0 (-48.65%). YTD was 19.0 versus 41.0 (-53.66%). Yesterday the same Saturday tip printed Zig at 19.0 versus 9.0 (+111.11%). The 2026-10-03 baseline reprinted from 9.0 to 21.0 and flipped the 7D sign. Store the session pull. rust programming scored 27.0, up 50.0% from 18.0. 12M was 27.0 versus 32.0 (-15.62%). YTD was 27.0 versus 30.0 (-10.0%). Yesterday Rust reprinted 26.0 versus 18.0. nim programming scored 13.0, up 85.71% from 7.0. 12M was 13.0 versus 32.0 (-59.38%). YTD baselined at 0.0. Report 13.0 versus 0.0. Yesterday Nim reprinted 14.0 versus 10.0. go programming scored 16.0, down 46.67% from 30.0. 12M was 16.0 versus 49.0 (-67.35%). YTD was 16.0 versus 33.0 (-51.52%). Do not copy 27.0, 19.0, 13.0, or 16.0 onto crystal programming 4.0.

get_time_series for crystal on Google Search closed at 33 on 2026-10-10, matching get_growth 33.0. Adjacent weeks: 42 on 2026-10-03, 53 on 2026-09-26, 54 on 2026-09-19, 52 on 2026-09-12, 53 on 2026-09-05. The series has 261 weekly points from 2021-10-16 through 2026-10-10. Peak in this pull is 100 on 2026-03-07. Tip 33 is not that March 2026 peak.

get_time_series for crystal programming closed at 4 on 2026-10-10, matching get_growth 4.0. Adjacent weeks: 25 on 2026-10-03, 62 on 2026-09-26, 44 on 2026-09-19, 39 on 2026-09-12, 38 on 2026-09-05. Peak in this pull is 100 on 2026-02-21. The phrase token sat at 62 two weeks before the tip, then printed 25 and 4. Same week as the short token's close of 33. A Rust sibling of this helper is on Rust Trends API. An Erlang sibling is on Erlang Trends API.

What did YouTube, News, and Wikipedia return?

YouTube get_growth for crystal tipped 43.0 on 2026-10-10, down 2.27% from 44.0, a shallower 7D drop than Search -21.43%. 14D was 43.0 versus 42.0 (+2.38%). 30D was 43.0 versus 46.0 (-6.52%). 3M was 43.0 versus 45.0 (-4.44%). 12M was 43.0 versus 48.0 (-10.42%). YTD was 43.0 versus 47.0 (-8.51%). YTD signs agree with Search -58.75% in direction and disagree in size. get_time_series closed at 43 on 2026-10-10, matching get_growth. Adjacent weeks: 44 on 2026-10-03, 42 on 2026-09-26, 46 on 2026-09-19, 46 on 2026-09-12. Peak in this pull is 100 on 2021-12-11. On 2026-03-07 Search printed 100 while YouTube printed 68. YouTube 43.0 is not Search 33.0. Do not copy the YouTube 7D of -2.27% onto a Search drop of -21.43%.

YouTube for crystal programming tipped 11.0 on 2026-10-10, up 37.5% from 8.0. Opposite 7D sign from Search programming -84.0%. 14D, 30D, 3M, and 12M baselined at 0.0 and printed growth 999999. Report 11.0 versus 0.0. YTD was 11.0 versus 70.0 (-84.29%). data_quality was low. YouTube programming 11.0 is not Search programming 4.0 and is not bare YouTube 43.0.

Keyword Google News for crystal tipped 21.0 on 2026-10-10, up 320.0% from 5.0. Opposite 7D sign from Search -21.43%. 14D was 21.0 versus 6.0 (+250.0%). 30D was 21.0 versus 12.0 (+75.0%). 3M was 21.0 versus 3.0 (+600.0%). 12M was 21.0 versus 3.0 (+600.0%). YTD was 21.0 versus 5.0 (+320.0%). get_time_series closed at 21, matching get_growth. Adjacent weeks: 5 on 2026-10-03, 6 on 2026-09-26, 7 on 2026-09-19, 12 on 2026-09-12. Peak in this pull is 100 on 2026-08-29. Tip 21 is not a new News high. On 2026-03-07 Search printed 100 while News printed 28. News 7D +320.0% does not lead Search 7D -21.43%. Keyword News and the Google News Top News board are different feeds. Do not fill News from Search 33.0.

Wikipedia resolved two titles. Keyword Crystal (programming language) resolved with September score 35.3 and 2,124 views versus August 5.5 / 1,524 (score +541.82%, volume +39.37%). 3M volume was 2,124 versus 1,462 in June (+45.28%) with score 35.3 versus 2.4. 12M volume was 2,124 versus 1,923 on 2025-09-01 (+10.45%) while the score went 35.3 versus 25.3 (+39.53%). YTD volume was 2,124 versus 2,152 (-1.3%) with score 35.3 versus 36.7 (-3.81%). 7D collapsed to the same monthly point. Report both score and volume.

Keyword Crystal is a different page. September score 3.3 with 15,825 views versus August 3.3 / 15,834 (score 0.0%, volume -0.06%). 3M volume was 15,825 versus 14,735 (+7.4%) while the score went 3.3 versus 0.0. 12M volume was 15,825 versus 19,244 (-17.77%). YTD volume was 15,825 versus 17,054 (-7.21%). The short title has more September views than the language page (15,825 versus 2,124). Same split as Nim, opposite of Erlang, where the long title held the traffic. Compare Wikipedia on volume. Do not join either page onto Search 33.0. Notes for the Wikipedia source sit on Wikipedia Trends.

How does a watchlist store live boards next to weekly scores?

get_top_trends has no keyword. It returns a ranked board. Pair it with get_growth for the tokens that appear, using the exact board string.

{"mode":"get_top_trends","type":"Google Trends","limit":25}
{"mode":"get_top_trends","type":"Google Trends","sort":"rank_change","window":"1d","limit":25}

The Google Trends board at 2026-10-15T10:01:38Z ranked rj mitte 1 and katie zacharia 2. The 1-day rank_change sort (25 rows, baseline 2026-10-14T02:01:40Z) listed katie zacharia at rank 2 with rank_change +7 from prev_rank 9. The 7-day sort returned 0 rows (baseline 2026-10-08T02:01:30Z) with a note that the board turned over completely and no item appeared in both snapshots. Weekly Search for katie zacharia was 17.0 versus 0.0 on 7D. Live rank 2 with 1d +7 is not weekly Search 17.0 versus 0.0. The walk-through is Katie Zacharia live rank versus weekly Search.

A Crystal watchlist that stores five Search tokens (crystal, crystal programming, crystal language, zig programming, rust programming) plus one YouTube series plus one Google Trends board uses 7 successful 200s. Four runs per 30-day month is 28 calls and fits the free cap of 100. Daily polling of that set is about 210 calls and needs Starter (5,000). Modes and sources for the modes live at https://trendsapi.ai/docs. Google Search board strings are not always valid get_growth keywords. Pair get_top_trends rank, rank_change, and get_growth before writing an alert. Source notes for Search sit on Google Trends.

Envelope checklist

1. POST https://api.trendsapi.ai/api with Authorization: Bearer <api_key>.
2. Modes are get_time_series, get_growth, and get_top_trends only.
3. Parse body twice before reading results or dated points.
4. Google Search uses the exact token typed. crystal, crystal programming, and crystal language are three series. shards without a language qualifier is another series. Wikipedia titles are resolved names; confirm the title and compare on volume before joining.
5. Quota counts successful 200 responses: free 100/month, then 5,000 / 25,000 / 100,000 on paid tiers.

No Crystal library is required. A 20-line HTTP::Client helper covers growth, series, and board pulls for jobs that already run under systemd or a cron timer.