Call Trends API from Kotlin with OkHttp

A Kotlin 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 Maven artifact. OkHttp sends the request. kotlinx.serialization parses the envelope, then parses the body string a second time. Pulled on 2026-09-11, Google Search for kotlin scored 34.0 for the week of 2026-09-05, up 6.25% from 32.0. kotlin programming scored 29.0, down 27.5% from 40.0. jetpack compose scored 47.0, up 104.35% from 23.0. Do not treat the Compose 7D spike as language adoption. The same helper that stores those rows also pulls a live Google Trends board; a 1-day climber on that board is documented in Sandra Bullock live rank versus weekly Search.

How does a Kotlin 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":"kotlin","percent_growth":["7D","30D","3M","12M"]}

import kotlinx.serialization.json.Json
import kotlinx.serialization.json.jsonObject
import kotlinx.serialization.json.jsonPrimitive
import okhttp3.MediaType.Companion.toMediaType
import okhttp3.OkHttpClient
import okhttp3.Request
import okhttp3.RequestBody.Companion.toRequestBody

fun trendsPost(payload: String): kotlinx.serialization.json.JsonElement {
    val key = System.getenv("TRENDSAPI_API_KEY")
        ?: error("TRENDSAPI_API_KEY is unset")
    val body = payload.toRequestBody("application/json".toMediaType())
    val req = Request.Builder()
        .url("https://api.trendsapi.ai/api")
        .addHeader("Authorization", "Bearer $key")
        .post(body)
        .build()
    OkHttpClient().newCall(req).execute().use { resp ->
        if (resp.code != 200) error("HTTP ${resp.code}")
        val envelope = Json.parseToJsonElement(resp.body!!.string()).jsonObject
        // body is a JSON string; parse it a second time
        val inner = envelope["body"]?.jsonPrimitive?.content
            ?: error("missing body")
        return Json.parseToJsonElement(inner)
    }
}

fun main() {
    val inner = trendsPost(
        """{"mode":"get_growth","source":"google search","keyword":"kotlin","percent_growth":["7D","30D","3M","12M"]}"""
    )
    println(inner)
}

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

https://square.github.io/okhttp/
https://github.com/Kotlin/kotlinx.serialization

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 Kotlin-specific source on this API. npm covers npmjs package names. python covers PyPI project names. A Kotlin watchlist that needs Maven Central download counts has to pull those from somewhere else.

What did get_growth return for Kotlin language tokens?

Pulled on 2026-09-11 with source set to google search. get_growth tips on 2026-09-05. The prior Saturday 2026-08-29 is the last full week in the same series.

kotlin and kotlin programming moved in opposite directions on 7D. The short language token rose 6.25%. The phrase token fell 27.5%. jetpack compose more than doubled on 7D (47.0 versus 23.0) while ktor fell 16.67% to 35.0 and kotlin multiplatform fell 8.7% to 21.0. A job that alerts "Kotlin is up" off Compose 7D is reading the UI toolkit series. Store each string.

3M is a summer crash on almost every token. kotlin is 34.0 versus 92.0 on 2026-06-06 (-63.04%). kotlin programming is 29.0 versus 100.0 (-71.0%). kotlin multiplatform is 21.0 versus 93.0 (-77.42%). ktor is 35.0 versus 90.0 (-61.11%). kotlinx is 37.0 versus 68.0 (-45.59%). jetpack compose is 47.0 versus 97.0 (-51.55%). jetbrains scored 30.0 versus 32.0 on 7D (-6.25%) and 30.0 versus 96.0 on 3M (-68.75%). Do not alert language adoption off a framework 3M crash. YouTube for the same language token is milder (next section).

get_time_series for kotlin on Google Search closed at 34 on 2026-09-05, matching get_growth 34.0. Adjacent weeks: 32 on 2026-08-29, 37 on 2026-08-22, 45 on 2026-08-08, 65 on 2026-08-01. The series hit 100 on 2026-05-30 and again on 2026-06-20, with 96 on 2026-05-16 and 92 on 2026-06-06. The 2025-09-06 close was 62. The 2026-01-03 close was 31. The 7D rise from 32 to 34 sits at the bottom of that summer drop, not at a new high.

kotlinlang is a sparse series. Tip 6.0 versus 2.0 on 7D (+200.0%) and versus 42.0 on 14D (-85.71%). 30D, 12M, and YTD baselined at 0.0 and printed growth 999999. Report 6.0 versus 0.0. Do not store 999999. Concatenated domain tokens are not the language token.

java Search tipped 47.0, flat versus 47.0 on 7D, with estimated volume 1,610,000 versus 1,610,000. 3M was 47.0 versus 81.0 (-41.98%) with baseline volume 2,770,000. The kotlin Search payload in this pull did not include volume fields. Do not copy Java volume onto Kotlin. The Java HttpClient sibling of this helper is Java Trends API.

What did YouTube, News, and Wikipedia return?

YouTube for kotlin tipped 28.0 on 2026-09-05, flat versus 28.0 on 2026-08-29. 14D was 28.0 versus 30.0 (-6.67%). 30D was 28.0 versus 27.0 (+3.7%). 3M was 28.0 versus 32.0 (-12.5%). 12M was 28.0 versus 40.0 (-30.0%). YTD was 28.0 versus 32.0 (-12.5%). Search 3M was -63.04%. YouTube 3M was -12.5%. A Search summer crash is not a YouTube crash.

YouTube for kotlin programming moved the other way on 7D. It tipped 20.0, up 233.33% from 6.0 on 2026-08-29, while Search for the same phrase fell 27.5%. 30D was 20.0 versus 0.0, which printed growth 999999. Report 20.0 versus 0.0. 3M was 20.0 versus 27.0 (-25.93%). 12M was 20.0 versus 0.0. Phrase YouTube and phrase Search are not one series.

Keyword Google News for kotlin tipped 41.0 on 2026-09-05, up 41.38% from 29.0 on 2026-08-29. 30D was 41.0 versus 24.0 (+70.83%). 3M and 12M baselined at 0.0 and printed growth 999999. The payload marked data_quality low with a warning that the underlying signal is over 90% zeros. Report 41.0 versus 0.0. News 7D is up while kotlin programming Search is down. Keyword News and the Google News Top News board are different feeds. news volume returned a 504 gateway timeout in this session. Store the timeout. Do not fill News from Search 34.0.

Wikipedia resolved two titles. Keyword kotlin resolved to Kotlin with August score 81.3 and 10,127 views versus July 85.3 / 10,594 (score -4.69%, volume -4.41%). 3M was 81.3 / 10,127 versus May 87.2 / 10,813. YTD was 81.3 / 10,127 versus January 90.8 / 11,242 (score -10.46%, volume -9.92%). 12M was 81.3 versus 0.2 on 2025-08-01 (+40550.0%) while volume was 10,127 versus 601 (+1585.02%). 7D and 14D collapsed to the same monthly point. Report both score and volume. Do not treat 81.3 as language demand.

Keyword Kotlin (programming language) is a different page. August score 0.0 with 1,953 views versus July 1.8 / 2,640 (score -100.0%, volume -26.02%). 3M volume was 1,953 versus 2,519 (-22.47%). 12M volume was 1,953 versus 16,983 on 2025-08-01 (-88.5%) while the score went 0.0 versus 38.5 (-100.0%). YTD volume was 1,953 versus 3,935 (-50.37%). The language page has fewer August views than the short title (1,953 versus 10,127). Compare Wikipedia on volume. Do not join either page onto Search 34.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-09-11T08:01:37Z ranked labor day 1, iphone duo 2, iphone 18 3, and sandra bullock 14. The 1-day rank_change sort (25 rows, baseline 2026-09-10T02:01:40Z) put sandra bullock at rank 14 with rank_change 133 from prev_rank 147. The 7-day sort returned 7 rows and omitted that name. Weekly Search for the same name was 26.0, up 8.33% from 24.0. Live rank and weekly 7D growth can disagree. The walk-through is Sandra Bullock live rank versus weekly Search.

A Kotlin watchlist that stores six Search tokens (kotlin, kotlin programming, jetpack compose, kotlinx, ktor, java) 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.

The Rust sibling of this helper is Rust Trends API. The Python sibling is Python Trends API. The Go sibling is Go Trends API.

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. kotlin, kotlin programming, kotlinlang, jetpack compose, ktor, and kotlin multiplatform are six 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 Maven SDK is required. A 40-line OkHttp helper covers growth, series, and board pulls for jobs that already run under cron or a systemd timer.