Laravel Semrush Laravel Package

Product Decisions This Supports

• Build vs. buy for SEO/competitive-intelligence features. This package is the "buy the plumbing" answer: it removes the cost of writing and maintaining a Semrush HTTP client, CSV parser, and error-mapping layer, so the team spends its effort on the product surface (scoring, dashboards, alerts) rather than transport code. A useful forcing question: is our differentiation in the SEO recommendations we generate, or in how we call Semrush? If the former, adopt; if the latter, this package is not the constraint either way.
• Feature scoping for an SEO or competitive-analysis module. The three report families map cleanly to shippable increments, which makes roadmap slicing straightforward:
  • Domain Overview + Domain Organic → "How big is this site's search footprint?" (market/competitor snapshot)
  • Domain Competitors + Keyword Overview → "Who are we actually losing to, and on which terms?" (competitive gap analysis)
  • Related Keywords + Keyword Difficulty → content/SEO planning and prioritization tooling
  • Backlinks Overview + Backlinks → link-profile health, digital PR, or outreach workflows
  • get() → a deliberate hedge: any report not yet wrapped is still reachable, so roadmap items aren't blocked on package releases. Treat it as the escape valve for one-off or experimental reports, not as the primary interface.
• Unit economics and pricing decisions. Semrush API access is metered in API units, and every one of these methods consumes them. This is the single most important product constraint: per-user dashboards, background refreshes, and "live" queries have real marginal cost. Adoption should trigger a decision on caching TTLs, refresh cadence, and whether expensive reports are gated behind a paid tier or quota. Without that, a "free live SEO panel" can quietly become a cost center.
• Data-freshness and UX commitments. The package returns whatever Semrush reports for the requested database (configurable via SEMRUSH_DATABASE); it adds no persistence or snapshotting. Any "trend over time," "change since last week," or alerting feature therefore needs our own storage layer — which is a separate roadmap item and should be scoped and estimated as such, not assumed to come free with the client.
• Reliability expectations and support load. Error mapping is already opinionated and useful: Semrush's habit of returning HTTP 200 with an ERROR body is converted into a SemrushException, and transport/HTTP failures become RequestException. That distinction is exactly what a PM needs to specify differentiated UX (bad key or exhausted units vs. transient outage vs. bad query parameters) and to decide retry/backoff behavior.

When to Consider This Package

Adopt when most of the following hold:

• Semrush is already, or is about to be, the chosen data source — either an existing subscription or a deliberate procurement decision. This package is a client, not a data source; it adds zero value without credentials.
• You are on Laravel and want configuration to flow through the framework's conventions (SEMRUSH_API_KEY / SEMRUSH_DATABASE, plus the services.semrush.key fallback for apps that centralize third-party credentials in config/services.php). The fallback matters operationally: it means secrets can be managed the same way as every other service, rather than as a bespoke env var.
• Your use cases sit inside the wrapped report set — domain, keyword, or backlink analysis. If they do, this is close to a drop-in.
• You want a thin, legible dependency. The surface is small and predictable: typed methods, plain associative arrays out, exceptions for failures. No models, no migrations, no queue workers, no opinion about storage. That is a good fit for teams that want to own their own domain layer.
• You accept that you own the operational envelope. Rate limiting, caching, retries, unit-budget monitoring, and cost attribution are not in scope here.

Look elsewhere or plan to build wrapping layers when:

• You are not on Laravel — the value is mostly idiomatic config and container integration; a plain PHP or framework-agnostic client would be a better dependency.
• You need throughput, resilience, or scale guarantees. There is no built-in caching, queuing, or rate-limit handling. High-volume or user-facing real-time usage requires us to add a caching/queue layer regardless of which client we pick.
• You need report types outside the wrapped set at meaningful scale. The get() escape hatch covers occasional reports, but a core workflow built entirely on raw get() calls means we are effectively maintaining our own client through a thin proxy — at that point, evaluate whether a first-class client for that report family is a better investment.
• Semrush's data model doesn't match your product. If you need search-console data, first-party analytics, or multi-provider comparison, this is one input among several — evaluate an aggregation layer, not just a client.
• Vendor lock-in is a live strategic concern. These methods are Semrush-shaped by design. If provider portability is a requirement, insist on an internal interface in front of this package from day one.

How to Pitch It (Stakeholders)

For executives (one paragraph): This is a small, low-risk integration library that lets our Laravel application pull competitive and keyword data from Semrush — the industry-standard SEO dataset — without building and maintaining that connection ourselves. It covers the three areas that matter for an SEO or competitive-intelligence feature: how large a site's search presence is, which keywords it wins and loses, and who it competes with for them. The engineering cost is minimal and the code surface is deliberately narrow, so it doesn't lock us into an architecture. The real decision it forces is commercial, not technical: Semrush API usage is metered, so any user-facing or automated feature needs a stated refresh cadence, caching policy, and cost ceiling before launch. Approve this as the plumbing; the accompanying decision to make is the monthly API budget and which features sit behind it.

For engineering (summary): A thin Laravel wrapper over the Semrush Analytics API. Typed methods for domain (domainOverview, domainOrganic, domainCompetitors), keyword (keywordOverview, relatedKeywords, keywordDifficulty), and backlink (backlinksOverview, backlinks) reports, plus a get() passthrough for anything else. Responses are semicolon-delimited CSV decoded into plain associative rows — no models, no DTOs, no persistence, so the mapping to our domain objects is ours to own. Error handling is already sensible and worth preserving: Semrush returns HTTP 200 with an ERROR body on failure, which this surfaces as SemrushException; non-2xx responses raise RequestException. That distinction lets us separate "fix the key / top up units / fix the query" from "retry later" — please keep it intact rather than collapsing to a single exception. Configuration is via SEMRUSH_API_KEY and SEMRUSH_DATABASE, with a services.semrush.key fallback so credentials can live in config/services.php alongside our other integrations. Explicitly out of scope and ours to build: caching, rate limiting, retry/backoff, unit-consumption monitoring, and any snapshotting needed for trend or change-over-time features. Recommend we treat the unit budget as a first-class non-functional requirement and add a caching layer before any endpoint is exposed to end users.