SemRush Research Pull live SEO and competitive intelligence data from the SemRush API. Prerequisites Requires SEMRUSH_API_KEY set in .env , .env.local , or ~/.claude/.env.global .
Verify the key is available
echo "SEMRUSH_API_KEY is ${SEMRUSH_API_KEY :+ set} " If the key is not set, instruct the user: You need a SemRush API key. Get one at https://www.semrush.com/api/ Then add SEMRUSH_API_KEY=your_key to your .env file. API Base All requests go to https://api.semrush.com/ with the API key passed as &key={SEMRUSH_API_KEY} . Responses are semicolon-delimited CSV. The first line is the header row. Parse accordingly. 1. Domain Overview Get a high-level snapshot of any domain's organic and paid search performance. Endpoint https://api.semrush.com/?type=domain_ranks&key={KEY}&export_columns=Dn,Rk,Or,Ot,Oc,Ad,At,Ac&domain={domain} Export Columns Column Meaning Dn Domain Rk SemRush Rank Or Organic keywords count Ot Organic traffic estimate Oc Organic traffic cost ($) Ad Paid keywords count At Paid traffic estimate Ac Paid traffic cost ($) Example curl curl -s "https://api.semrush.com/?type=domain_ranks&key= ${SEMRUSH_API_KEY} &export_columns=Dn,Rk,Or,Ot,Oc,Ad,At,Ac&domain=example.com" Parsing the Response
Response format (semicolon-delimited):
Dn;Rk;Or;Ot;Oc;Ad;At;Ac
example.com;12345;8234;145000;234500;120;3400;5600
Parse with awk
- curl
- -s
- "..."
- |
- awk
- -F
- ';'
- 'NR==2 {
- printf "Domain: %s\nSemRush Rank: %s\nOrganic Keywords: %s\nOrganic Traffic: %s\nOrganic Traffic Cost: $%s\nPaid Keywords: %s\nPaid Traffic: %s\nPaid Traffic Cost: $%s\n",
- $1,$2,$3,$4,$5,$6,$7,$8
- }'
- 2. Keyword Overview
- Get search volume, CPC, competition, and SERP features for a keyword.
- Endpoint
- https://api.semrush.com/?type=phrase_all&key={KEY}&phrase={keyword}&database=us&export_columns=Ph,Nq,Cp,Co,Nr,Td
- Export Columns
- Column
- Meaning
- Ph
- Keyword phrase
- Nq
- Search volume (monthly)
- Cp
- CPC (USD)
- Co
- Competition (0-1)
- Nr
- Number of results
- Td
- Trend (12 months, comma-separated)
- Example curl
- curl
- -s
- "https://api.semrush.com/?type=phrase_all&key=
- ${SEMRUSH_API_KEY}
- &phrase=content+marketing&database=us&export_columns=Ph,Nq,Cp,Co,Nr,Td"
- Supported Databases
- Use
- &database=XX
- where XX is:
- us
- ,
- uk
- ,
- ca
- ,
- au
- ,
- de
- ,
- fr
- ,
- es
- ,
- it
- ,
- br
- ,
- in
- ,
- jp
- .
- 3. Related Keywords
- Find semantically related keywords for content planning and gap analysis.
- Endpoint
- https://api.semrush.com/?type=phrase_related&key={KEY}&phrase={keyword}&database=us&export_columns=Ph,Nq,Cp,Co,Nr,Td&display_limit=20
- Example curl
- curl
- -s
- "https://api.semrush.com/?type=phrase_related&key=
- ${SEMRUSH_API_KEY}
- &phrase=project+management&database=us&export_columns=Ph,Nq,Cp,Co,Nr,Td&display_limit=20"
- Parsing Multiple Rows
- curl
- -s
- "..."
- |
- awk
- -F
- ';'
- 'NR>1 { printf "%-40s Vol: %-8s CPC: $%-6s Comp: %s\n", $1, $2, $3, $4 }'
- 4. Keyword Difficulty
- Estimate how hard it is to rank for a keyword.
- Endpoint
- https://api.semrush.com/?type=phrase_kdi&key={KEY}&phrase={keyword}&database=us&export_columns=Ph,Kd
- Column
- Meaning
- Ph
- Keyword
- Kd
- Keyword difficulty (0-100)
- Interpretation:
- 0-29: Easy - achievable with quality content
- 30-49: Moderate - needs solid content + some backlinks
- 50-69: Hard - needs strong domain authority + backlinks
- 70-84: Very hard - requires established authority
- 85-100: Extremely hard - dominated by top-tier domains
- 5. Domain Organic Keywords
- See which keywords a domain ranks for organically.
- Endpoint
- https://api.semrush.com/?type=domain_organic&key={KEY}&domain={domain}&database=us&export_columns=Ph,Po,Nq,Cp,Url,Tr,Tc&display_limit=50&display_sort=tr_desc
- Column
- Meaning
- Ph
- Keyword
- Po
- Position
- Nq
- Search volume
- Cp
- CPC
- Url
- Ranking URL
- Tr
- Traffic (%)
- Tc
- Traffic cost
- Example curl
- curl
- -s
- "https://api.semrush.com/?type=domain_organic&key=
- ${SEMRUSH_API_KEY}
- &domain=hubspot.com&database=us&export_columns=Ph,Po,Nq,Cp,Url,Tr,Tc&display_limit=20&display_sort=tr_desc"
- 6. Backlink Overview
- Get a summary of a domain's backlink profile.
- Endpoint
- https://api.semrush.com/analytics/v1/?key={KEY}&type=backlinks_overview&target={domain}&target_type=root_domain&export_columns=total,domains_num,urls_num,ips_num,follows_num,nofollows_num,texts_num,images_num
- Example curl
- curl
- -s
- "https://api.semrush.com/analytics/v1/?key=
- ${SEMRUSH_API_KEY}
- &type=backlinks_overview&target=example.com&target_type=root_domain&export_columns=total,domains_num,urls_num,ips_num,follows_num,nofollows_num,texts_num,images_num"
- 7. Competitor Discovery
- Find domains competing for the same organic keywords.
- Endpoint
- https://api.semrush.com/?type=domain_organic_organic&key={KEY}&domain={domain}&database=us&export_columns=Dn,Cr,Np,Or,Ot,Oc,Ad&display_limit=10
- Column
- Meaning
- Dn
- Competitor domain
- Cr
- Competition level
- Np
- Common keywords
- Or
- Organic keywords
- Ot
- Organic traffic
- Oc
- Organic traffic cost
- Ad
- Paid keywords
- Example curl
- curl
- -s
- "https://api.semrush.com/?type=domain_organic_organic&key=
- ${SEMRUSH_API_KEY}
- &domain=notion.so&database=us&export_columns=Dn,Cr,Np,Or,Ot,Oc,Ad&display_limit=10"
- 8. Traffic Analytics (Estimates)
- Estimate a domain's overall traffic sources and engagement.
- Endpoint
- https://api.semrush.com/analytics/ta/api/v3/summary?key={KEY}&targets={domain}&display_date=2024-01-01&country=us&export_columns=target,visits,users,bounce_rate,pages_per_visit,avg_visit_duration
- Workflow: Full Competitive Analysis
- When the user asks for a full competitive analysis, run these steps in order:
- Domain Overview
- - Get the target domain's metrics
- Competitor Discovery
- - Find top 5-10 competitors
- Domain Overview
- for each competitor - Compare metrics
- Top Keywords
- for each domain - Find keyword gaps
- Backlink Overview
- for each domain - Compare link profiles
- Output Format
- Present results as a comparison table:
- | Metric | target.com | competitor1.com | competitor2.com |
- |---------------------|-----------|-----------------|-----------------|
- | SemRush Rank | ... | ... | ... |
- | Organic Keywords | ... | ... | ... |
- | Organic Traffic | ... | ... | ... |
- | Traffic Cost | ... | ... | ... |
- | Backlinks | ... | ... | ... |
- | Referring Domains | ... | ... | ... |
- Then highlight:
- Keyword gaps
-
- Keywords competitors rank for but target does not
- Quick wins
-
- Keywords where target ranks positions 5-20 (improvement opportunities)
- Content gaps
-
- Topics competitors cover but target does not
- Backlink opportunities
- Sites linking to competitors but not target Rate Limits and Costs Each API call costs API units (check your plan) Use &display_limit= to control result count (default varies by endpoint) Cache results locally when doing multi-step analysis to avoid redundant calls Domain overview calls are cheapest; backlink and traffic analytics cost more Error Handling Error Meaning ERROR 50 :: NOTHING FOUND No data for this query ERROR 120 :: WRONG KEY Invalid API key ERROR 130 :: LIMIT EXCEEDED API unit limit reached Empty response Usually means no data available for the query parameters When you get "NOTHING FOUND", try: Different database (e.g., uk instead of us ) Root domain instead of subdomain Broader keyword phrase