Laravel Semrush

https://github.com/jeffersongoncalves/laravel-semrush
Admin
Laravel Semrush is a lightweight Semrush Analytics API client for Laravel that wraps domain...
Tokens:5,047
Snippets:41
Trust Score:9.8
License:MIT
Update:1 month ago
Show doc for...
Tokens:
Raw
### Install laravel-semrush with Composer

Source: https://github.com/jeffersongoncalves/laravel-semrush/blob/main/README.md

Install the package via Composer.

```bash
composer require jeffersongoncalves/laravel-semrush
```

--------------------------------

### Return shape example with keywordOverview

Source: https://github.com/jeffersongoncalves/laravel-semrush/blob/main/README.md

Every method returns a list of rows keyed by the report's export_columns. Values are always strings; cast them yourself where you need numbers.

```php
Semrush::keywordOverview('laravel');

// [
//     ['Ph' => 'laravel', 'Nq' => '12100', 'Cp' => '1.35', 'Co' => '0.07', 'Nr' => '154000000'],
// ]
```

--------------------------------

### Call any report via Semrush::get()

Source: https://github.com/jeffersongoncalves/laravel-semrush/blob/main/README.md

Use get() for any Semrush report type. It appends the key, escapes the export, and decodes the CSV for you.

```php
Semrush::get([
    'type' => 'phrase_this',
    'phrase' => 'laravel',
    'database' => 'us',
    'export_columns' => 'Ph,Nq,Cp',
]);
```

--------------------------------

### Semrush Error Test Example

Source: https://github.com/jeffersongoncalves/laravel-semrush/blob/main/resources/boost/skills/semrush-development/SKILL.md

This test verifies that a SemrushException is thrown when the API response body contains an error message. It uses Http::fake with an ERROR body and expects the exception.

```php
it('throws a SemrushException when the body reports an error', function () {
    Http::fake([
        'api.semrush.com/*' => csv('ERROR 50 :: NOTHING FOUND'),
    ]);

    expect(fn () => app(Semrush::class)->keywordOverview('laravel'))
        ->toThrow(SemrushException::class);
});
```

--------------------------------

### Use Semrush facade methods

Source: https://github.com/jeffersongoncalves/laravel-semrush/blob/main/README.md

Use the facade to call all available report methods. Optional 'database' and 'limit' parameters are omitted from the query when left null.

```php
use JeffersonGoncalves\Semrush\Facades\Semrush;

Semrush::domainOverview('example.com');

Semrush::domainOrganic('example.com', database: 'br', limit: 50);

Semrush::domainCompetitors('example.com', limit: 20);

Semrush::keywordOverview('laravel', database: 'us');

Semrush::relatedKeywords('laravel', database: 'us', limit: 25);

Semrush::keywordDifficulty('laravel');

Semrush::backlinksOverview('example.com');

Semrush::backlinks('example.com', targetType: 'domain', limit: 100);
```

--------------------------------

### Configure SEMRUSH_API_KEY and SEMRUSH_DATABASE

Source: https://github.com/jeffersongoncalves/laravel-semrush/blob/main/README.md

Add these environment variables to your .env file. The API key is required; the database defaults to 'us'.

```env
SEMRUSH_API_KEY=your-semrush-api-key
SEMRUSH_DATABASE=us
```

--------------------------------

### Format code with composer format

Source: https://github.com/jeffersongoncalves/laravel-semrush/blob/main/README.md

Formats the codebase according to the project's style guidelines using Composer. Use this command to ensure consistent code formatting.

```bash
composer format
```

--------------------------------

### Default semrush.php config

Source: https://github.com/jeffersongoncalves/laravel-semrush/blob/main/README.md

Default configuration file. When 'key' is null, the client falls back to config('services.semrush.key').

```php
// config/semrush.php
return [
    'key' => env('SEMRUSH_API_KEY'),
    'database' => env('SEMRUSH_DATABASE', 'us'),
    'base_url' => env('SEMRUSH_BASE_URL', 'https://api.semrush.com'),
];
```

--------------------------------

### Run static analysis with composer analyse

Source: https://github.com/jeffersongoncalves/laravel-semrush/blob/main/README.md

Runs static analysis on the codebase using Composer. Use this command to check for potential issues without executing the code.

```bash
composer analyse
```

--------------------------------

### Run tests with composer test

Source: https://github.com/jeffersongoncalves/laravel-semrush/blob/main/README.md

Runs the test suite for the package using Composer. Use this command to execute all tests defined in the project.

```bash
composer test
```

--------------------------------

### Publish semrush-config

Source: https://github.com/jeffersongoncalves/laravel-semrush/blob/main/README.md

Optionally publish the package's config file.

```bash
php artisan vendor:publish --tag="semrush-config"
```

--------------------------------

### Resolve Semrush client via app()

Source: https://github.com/jeffersongoncalves/laravel-semrush/blob/main/README.md

Inject or resolve the underlying client instead of using the facade.

```php
use JeffersonGoncalves\Semrush\Semrush;

$semrush = app(Semrush::class);
$semrush->domainOverview('example.com');
```

--------------------------------

### Semrush::key() - Resolve API key from config

Source: https://github.com/jeffersongoncalves/laravel-semrush/blob/main/resources/boost/skills/semrush-development/SKILL.md

Resolves the API key from config('semrush.key') (which reads env('SEMRUSH_API_KEY')) falling back to config('services.semrush.key'). Returns an empty string if the resolved value is not a string.

```php
private function key(): string
{
    $key = config('semrush.key') ?? config('services.semrush.key');

    return is_string($key) ? $key : '';
}
```

--------------------------------

### Semrush::keywordOverview()

Source: https://github.com/jeffersongoncalves/laravel-semrush/blob/main/README.md

Retrieves an overview of a keyword's SEO metrics from Semrush.

```APIDOC
## Semrush::keywordOverview()

### Description
Retrieves an overview of a keyword's SEO metrics from Semrush.

### Method
GET

### Endpoint
https://api.semrush.com/?type=phrase_this

### Parameters
#### Path Parameters
- **keyword** (string) - Required - The keyword to analyze.

#### Query Parameters
- **database** (string) - Optional - The database to use (e.g., 'us', 'br'). Defaults to configured database.
- **limit** (integer) - Optional - The maximum number of results to return.

### Response
#### Success Response (200)
- Returns an array of rows keyed by the report's export columns.

#### Response Example
```
[
    ['Ph' => 'laravel', 'Nq' => '12100', 'Cp' => '1.35', 'Co' => '0.07', 'Nr' => '154000000']
]
```
```

--------------------------------

### Semrush::get() - Build query and handle response

Source: https://github.com/jeffersongoncalves/laravel-semrush/blob/main/resources/boost/skills/semrush-development/SKILL.md

Core method of the Semrush client that builds the query, appends key and export_escape=1, filters null params, throws on non-2xx, raises SemrushException on ERROR bodies, and decodes CSV. Use as the escape hatch for report types not yet wrapped.

```php
public function get(array $query): array
{
    $query['key'] = $this->key();
    $query['export_escape'] = '1';

    $response = Http::baseUrl($this->baseUrl())
        ->get('/', array_filter($query, fn ($value) => $value !== null));

    $response->throw();

    $body = trim($response->body());

    if (str_starts_with($body, 'ERROR')) {
        throw new SemrushException($body);
    }

    return $this->parseCsv($body);
}
```

--------------------------------

### Semrush::domainOverview()

Source: https://github.com/jeffersongoncalves/laravel-semrush/blob/main/README.md

Retrieves an overview of a domain's SEO metrics from Semrush.

```APIDOC
## Semrush::domainOverview()

### Description
Retrieves an overview of a domain's SEO metrics from Semrush.

### Method
GET

### Endpoint
https://api.semrush.com/?type=domain_ranks

### Parameters
#### Path Parameters
- **domain** (string) - Required - The domain to analyze.

#### Query Parameters
- **database** (string) - Optional - The database to use (e.g., 'us', 'br'). Defaults to configured database.
- **limit** (integer) - Optional - The maximum number of results to return.

### Response
#### Success Response (200)
- Returns an array of rows keyed by the report's export columns.

#### Response Example
```
[
    ['Ph' => 'example.com', 'Nq' => '12100', 'Cp' => '1.35', 'Co' => '0.07', 'Nr' => '154000000']
]
```
```

--------------------------------

### Semrush::backlinksOverview()

Source: https://github.com/jeffersongoncalves/laravel-semrush/blob/main/README.md

Retrieves an overview of backlinks for a domain from Semrush.

```APIDOC
## Semrush::backlinksOverview()

### Description
Retrieves an overview of backlinks for a domain from Semrush.

### Method
GET

### Endpoint
https://api.semrush.com/?type=backlinks_overview

### Parameters
#### Path Parameters
- **domain** (string) - Required - The domain to analyze.

#### Query Parameters
- **database** (string) - Optional - The database to use (e.g., 'us', 'br'). Defaults to configured database.
- **limit** (integer) - Optional - The maximum number of results to return.

### Response
#### Success Response (200)
- Returns an array of rows keyed by the report's export columns.

#### Response Example
```
[
    ['Ph' => 'example.com', 'Nq' => '12100', 'Cp' => '1.35', 'Co' => '0.07', 'Nr' => '154000000']
]
```
```

--------------------------------

### Semrush::domainCompetitors()

Source: https://github.com/jeffersongoncalves/laravel-semrush/blob/main/README.md

Retrieves organic competitors for a domain from Semrush.

```APIDOC
## Semrush::domainCompetitors()

### Description
Retrieves organic competitors for a domain from Semrush.

### Method
GET

### Endpoint
https://api.semrush.com/?type=domain_organic_organic

### Parameters
#### Path Parameters
- **domain** (string) - Required - The domain to analyze.

#### Query Parameters
- **database** (string) - Optional - The database to use (e.g., 'us', 'br'). Defaults to configured database.
- **limit** (integer) - Optional - The maximum number of results to return.

### Response
#### Success Response (200)
- Returns an array of rows keyed by the report's export columns.

#### Response Example
```
[
    ['Ph' => 'example.com', 'Nq' => '12100', 'Cp' => '1.35', 'Co' => '0.07', 'Nr' => '154000000']
]
```
```

--------------------------------

### Semrush::get()

Source: https://github.com/jeffersongoncalves/laravel-semrush/blob/main/README.md

Executes any Semrush report type by passing the report parameters directly.

```APIDOC
## Semrush::get()

### Description
Executes any Semrush report type by passing the report parameters directly.

### Method
GET

### Endpoint
https://api.semrush.com/

### Parameters
#### Query Parameters
- **type** (string) - Required - The Semrush report type (e.g., 'phrase_this').
- **phrase** (string) - Optional - The keyword or phrase to analyze.
- **database** (string) - Optional - The database to use (e.g., 'us', 'br').
- **export_columns** (string) - Optional - Comma-separated list of columns to export.
- Additional parameters as required by the specific report type.

### Response
#### Success Response (200)
- Returns an array of rows keyed by the report's export columns.

#### Response Example
```
[
    ['Ph' => 'laravel', 'Nq' => '12100', 'Cp' => '1.35', 'Co' => '0.07', 'Nr' => '154000000']
]
```
```

--------------------------------

### Semrush Success Test: keywordOverview CSV Parsing

Source: https://github.com/jeffersongoncalves/laravel-semrush/blob/main/resources/boost/skills/semrush-development/SKILL.md

Tests that the keywordOverview method correctly parses a semicolon-separated CSV response into associative rows. Uses Http::fake to mock the API and asserts the returned array matches the expected data.

```php
it('parses a semicolon separated csv body into associative rows', function () {
    Http::fake([
        'api.semrush.com/*' => csv("Ph;Nq;Cp\nlaravel;12100;1.35\n"),
    ]);

    expect(app(Semrush::class)->keywordOverview('laravel'))->toBe([
        ['Ph' => 'laravel', 'Nq' => '12100', 'Cp' => '1.35'],
    ]);
});
```

--------------------------------

### Semrush::domainOrganic()

Source: https://github.com/jeffersongoncalves/laravel-semrush/blob/main/README.md

Retrieves organic keywords for a domain from Semrush.

```APIDOC
## Semrush::domainOrganic()

### Description
Retrieves organic keywords for a domain from Semrush.

### Method
GET

### Endpoint
https://api.semrush.com/?type=domain_organic

### Parameters
#### Path Parameters
- **domain** (string) - Required - The domain to analyze.

#### Query Parameters
- **database** (string) - Optional - The database to use (e.g., 'us', 'br'). Defaults to configured database.
- **limit** (integer) - Optional - The maximum number of results to return.

### Response
#### Success Response (200)
- Returns an array of rows keyed by the report's export columns.

#### Response Example
```
[
    ['Ph' => 'laravel', 'Nq' => '12100', 'Cp' => '1.35', 'Co' => '0.07', 'Nr' => '154000000']
]
```
```

--------------------------------

### Semrush::backlinks()

Source: https://github.com/jeffersongoncalves/laravel-semrush/blob/main/README.md

Retrieves a list of backlinks for a domain from Semrush.

```APIDOC
## Semrush::backlinks()

### Description
Retrieves a list of backlinks for a domain from Semrush.

### Method
GET

### Endpoint
https://api.semrush.com/?type=backlinks

### Parameters
#### Path Parameters
- **domain** (string) - Required - The domain to analyze.

#### Query Parameters
- **database** (string) - Optional - The database to use (e.g., 'us', 'br'). Defaults to configured database.
- **limit** (integer) - Optional - The maximum number of results to return.
- **targetType** (string) - Optional - The type of target (e.g., 'domain').

### Response
#### Success Response (200)
- Returns an array of rows keyed by the report's export columns.

#### Response Example
```
[
    ['Ph' => 'example.com', 'Nq' => '12100', 'Cp' => '1.35', 'Co' => '0.07', 'Nr' => '154000000']
]
```
```

--------------------------------

### Handle SemrushException and RequestException

Source: https://github.com/jeffersongoncalves/laravel-semrush/blob/main/README.md

Semrush reports errors with HTTP 200 and an 'ERROR ...' body, which raises SemrushException. Non-2xx responses raise Illuminate\Http\Client\RequestException.

```php
use Illuminate\Http\Client\RequestException;
use JeffersonGoncalves\Semrush\Exceptions\SemrushException;

try {
    $rows = Semrush::keywordOverview('laravel');
} catch (SemrushException $e) {
    // "ERROR 50 :: NOTHING FOUND", "ERROR 120 :: WRONG KEY", ...
} catch (RequestException $e) {
    // $e->response->status(), $e->response->body(), ...
}
```

--------------------------------

### Semrush::keywordDifficulty()

Source: https://github.com/jeffersongoncalves/laravel-semrush/blob/main/README.md

Retrieves the keyword difficulty score for a given keyword from Semrush.

```APIDOC
## Semrush::keywordDifficulty()

### Description
Retrieves the keyword difficulty score for a given keyword from Semrush.

### Method
GET

### Endpoint
https://api.semrush.com/?type=phrase_kdi

### Parameters
#### Path Parameters
- **keyword** (string) - Required - The keyword to analyze.

#### Query Parameters
- **database** (string) - Optional - The database to use (e.g., 'us', 'br'). Defaults to configured database.
- **limit** (integer) - Optional - The maximum number of results to return.

### Response
#### Success Response (200)
- Returns an array of rows keyed by the report's export columns.

#### Response Example
```
[
    ['Ph' => 'laravel', 'Nq' => '12100', 'Cp' => '1.35', 'Co' => '0.07', 'Nr' => '154000000']
]
```
```

--------------------------------

### Semrush::relatedKeywords()

Source: https://github.com/jeffersongoncalves/laravel-semrush/blob/main/README.md

Retrieves related keywords for a given keyword from Semrush.

```APIDOC
## Semrush::relatedKeywords()

### Description
Retrieves related keywords for a given keyword from Semrush.

### Method
GET

### Endpoint
https://api.semrush.com/?type=phrase_related

### Parameters
#### Path Parameters
- **keyword** (string) - Required - The keyword to analyze.

#### Query Parameters
- **database** (string) - Optional - The database to use (e.g., 'us', 'br'). Defaults to configured database.
- **limit** (integer) - Optional - The maximum number of results to return.

### Response
#### Success Response (200)
- Returns an array of rows keyed by the report's export columns.

#### Response Example
```
[
    ['Ph' => 'laravel', 'Nq' => '12100', 'Cp' => '1.35', 'Co' => '0.07', 'Nr' => '154000000']
]
```
```
Tokens:
Raw