Developers

Building with HitSonar?

Bring HitSonar’s YouTube research signals into your own application. The API returns the same analysis the product shows: one versioned HitSonar Score with its full breakdown, search demand as a band, the first page of results, and the queries people actually type.

Reference

The base URL is https://app.hitsonar.com. Every call except health needs an API key, sent as a bearer token:

Authorization: Bearer YOUR_API_KEY

Keys are issued per application during early access.

POST /v1/analyze

The full analysis for one phrase. Send phrase, and optionally geo (US today) and fresh: true to skip the cache. A cold run takes about twenty seconds; allow sixty.

score.overall is the only opportunity score. Display it; never compute your own.
score.version names the scoring model. Store it beside any score you keep: versions are not comparable.
analysisStatus is complete, degraded or provisional. Mark provisional scores as provisional on screen.
volumeStatus says where the search figure came from, including when a provider failed.
subscribers can be null when a channel hides its count. Never treat it as 0.

GET /v1/suggest?q=

Autocomplete only, in a few seconds. Returns the expanded suggestions and seedSuggestions, how many completions YouTube offered for the bare phrase. Four or fewer means almost nobody types it, which makes this the cheap check before a full run.

GET /v1/health

Open, no key. Reports what is switched on, the scoring version in force and the geographies supported.

Errors

400 phrase shorter than two characters, or an unsupported geo
401 missing or unknown key
503 the outside services did not answer; try again

Request

curl -X POST https://app.hitsonar.com/v1/analyze \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "phrase": "gospel blues", "geo": "US" }'

Response, shortened

{
  "phrase": "gospel blues",
  "geo": "US",
  "analysisStatus": "complete",
  "volumeStatus": "modeled",
  "seedSuggestions": 14,
  "score": {
    "version": "1.0.0",
    "overall": 72, "grade": "A",
    "demand": 69, "competition": 34,
    "searchBand": { "label": "100K to 1M" },
    "confidence": "medium",
    "explanation": { "...": "inputs, intermediate values and formulas" }
  },
  "trend": { "direction": "steady", "...": "..." },
  "ranking": { "phraseInTitleShare": 0.7, "medianSubscribers": 21100, "videos": ["..."] },
  "suggestions": ["..."]
}

New to HitSonar?

See what the analysis looks like for a creator before you build on it.

View Example Analysis