Przejdź do treści

Search intent and Needs Met

Two ways to use search intent: the Search Intent tool (a phrase and a market, no page needed) and the intent rules in a page check (below).

Market: country and language

A market is a country and a language from the supported lists (Google Search locations at country level and Google languages). In the panel both are searchable fields (type "Pol" and pick "Poland"); the last choice is remembered in the browser. In the API, CSV files and list lines the market is language-COUNTRY, e.g. en-US, pl-PL, pt-BR-BR: the language_code, a hyphen and the ISO country code. JSON requests can send location_code (e.g. 2616 = Poland) and language_code (e.g. pl) instead of market; the response always has market. An unknown country or language returns 422 validation_error.

Search Intent tool

In the panel: Search Intent in the sidebar. Enter one phrase with a country and a language, a list (one phrase per line, optional ,pl-PL after the phrase) or a CSV file (query, optional market like pl-PL, device; up to 100 phrases, duplicates run once). The report shows the intent shares, the recommended form, the typical length of top results, content elements, reader questions and the date of the search results snapshot. Export HTML, PDF or CSV, or share a read-only link.

curl -H "Authorization: Bearer $KEY" -H 'content-type: application/json' \
  -d '{"query": "best running shoes", "market": "en-US"}' "https://judge.example.com/v1/intent?wait=30"
curl -H "Authorization: Bearer $KEY" -H 'content-type: application/json' \
  -d '{"query": "kalkulator raty kredytu", "location_code": 2616, "language_code": "pl"}' https://judge.example.com/v1/intent
curl -H "Authorization: Bearer $KEY" https://judge.example.com/v1/intent/itr_...           # status and report
curl -H "Authorization: Bearer $KEY" -F file=@phrases.csv https://judge.example.com/v1/intent/batch/csv
  • POST /v1/intent returns 202 with status: queued; results usually take a few minutes. ?wait=N waits up to N seconds (max 60). POST /v1/intent/batch takes {"items": [{"query", "market"}]}.
  • GET /v1/intent lists the history (batch_id, q), GET /v1/intent/{id}/export.html|pdf|csv, GET /v1/intent/batches/{batch_id}/export.csv, POST /v1/intent/{id}/shares (see Sharing; not available in private projects).
  • tier: basic (default, available), premium and compare (coming soon; 422 tier_unavailable). Legacy ids: lite = basic, full = premium. Another value returns 422 validation_error. compare_url only with tier: compare. Older reports stored as lite are returned as basic.
  • freshness: auto (default) reuses search results not older than max_age_days (default 3, max 7); fresh always fetches new results at the full price. Each report has snapshot_at (date of the search results); GET /v1/intent?q=<phrase> lists earlier reports of a phrase to compare dates.
  • Price per phrase (basic): $0.0090 for new search results; $0.0015 when Ani reuses search results of the same phrase and market from the last max_age_days (checked by anyone); $0 when her analysis of those results is ready too. premium: $0.0750 (coming soon); compare: price at launch. A phrase that fails is not charged.

Intent in a page check

Give a page a target query and a market, and the report compares the page with what searchers of that query want. The search results (top 10 organic results) are grouped into searcher intents by a language model (intent-labeler, MIT). Shares, the dominant intent, the length range and the form gaps are computed by code.

Request

curl -H "Authorization: Bearer $KEY" -H 'content-type: application/json' \
  -d '{"url": "https://example.com/loan-calculator", "query": "loan installment calculator", "market": "en-US"}' \
  https://judge.example.com/v1/judge
  • query: up to 200 characters. Without it, the intent rules are listed under Not assessed.
  • market: language-COUNTRY, e.g. pl-PL, en-GB (default en-US).
  • Site audits: upload a CSV with the columns url,query,market (optional per row).

What you get

  • report.intent: the dominant intent and its share of the top results, the best form, the typical length (p25-p75 words of the dominant-intent pages), this page's length band and form gaps - elements that at least half of the dominant-intent pages have and this page lacks (table, calculator/form, FAQ, step list, video).
  • Two rules that need the query:
  • QR-NM - Needs Met rating (SQRG Part 3, sections 13-17): Fails to Meet, Slightly, Moderately, Highly, Fully Meets, shown as a distribution over the scale.
  • QR-HC-INTENT-MISMATCH - the page serves a different goal or a wrong form for the query (0/1).

Price

$0.0090 per unique query and market in a run; $0.0015 when the search results are cached, $0 when the intent profile is cached (7 days). Pages of one audit that share a query pay once.

Limits

  • The search results come from the configured provider. Until a paid SERP provider is enabled, only the demo queries from the intent-labeler examples are available; other queries return "Search intent was not assessed".
  • The intent labels are a reading of one results page at one moment; rankings change.