README

Laravel Client for the Podscan.fm API

This package provides a simple and easy-to-use API client for the Podscan.fm API

Installation

You can install the package via composer:

composer require helgesverre/laravel-podscan

You can publish the config file with:

php artisan vendor:publish --tag="podscan-config"

This is the contents of the published config file:

return [
    'api_key' => env('PODSCAN_API_KEY'),
];

Add your API key to your .env file:

PODSCAN_API_KEY=your_api_key_here

You can generate your API key at https://podscan.fm/user/api-tokens.

Rate Limits

The Podscan API enforces rate limits based on your subscription plan:

Plan	Daily Limit	Per Minute Limit
Trial	100 requests	10 requests
Essential	1,000 requests	60 requests
Premium	2,000 requests	120 requests
Enterprise	5,000 requests	120 requests

Every API response includes the following headers:

X-RateLimit-Limit: Maximum requests allowed in a 60-minute period
X-RateLimit-Remaining: Requests remaining in the current rate limit window

Error Handling

This package uses Saloon's AlwaysThrowOnErrors plugin, which automatically throws exceptions for 4xx and 5xx HTTP responses.

use Saloon\Exceptions\Request\FatalRequestException;
use Saloon\Exceptions\Request\RequestException;

try {
    $response = Podscan::podcasts()->get('podcast-id');
} catch (FatalRequestException $e) {
    // Handle 4xx errors (client errors)
    echo "Client error: " . $e->getMessage();
} catch (RequestException $e) {
    // Handle 5xx errors (server errors)
    echo "Server error: " . $e->getMessage();
}

Usage

Client Instantiation

Create an instance of the Podscan client to start interacting with the API. This instance will be your primary interface for sending requests to Podscan.AI.

use HelgeSverre\Podscan\Podscan;

// Instantiate the client
$podscan = new Podscan(apiKey: config('podscan.api_key'));

// Or use the Facade (Laravel)
Podscan::alerts();
Podscan::category();
Podscan::charts();
Podscan::episodes();
Podscan::podcasts();
Podscan::teams();

Resources

Alerts

Podscan::alerts()->list();
Podscan::alerts()->create();
Podscan::alerts()->get();
Podscan::alerts()->update();
Podscan::alerts()->delete();
Podscan::alerts()->mentions();
Podscan::alerts()->mention();

Charts

// Get countries with current chart data
Podscan::charts()->availableCountries();

// Get all supported countries
Podscan::charts()->supportedCountries();

// Get available categories for a platform and country
Podscan::charts()->categories('apple', 'US');
Podscan::charts()->categories('spotify', 'GB');

// Get chart data for a specific category
Podscan::charts()->categoryData('apple', 'US', 'technology');
Podscan::charts()->categoryData('spotify', 'GB', 'comedy');

Episodes

Podscan::episodes()->search();
Podscan::episodes()->paginatedSearch();
Podscan::episodes()->recent();
Podscan::episodes()->get();

Podcasts

Podscan::podcasts()->suggest();
Podscan::podcasts()->search();
Podscan::podcasts()->paginatedSearch();
Podscan::podcasts()->get();
Podscan::podcasts()->episodes();
Podscan::podcasts()->paginatedEpisodes();

Teams

Podscan::teams()->list();

Testing

cp .env.example .env
composer test
composer analyse src

License

The MIT License (MIT). Please see License File for more information.

Disclaimer

Podscan and the Podscan logo are trademarks of Arvid Kahl. This package is not affiliated with Podscan or Arvid Kahl in any way.

helgesverre / laravel-podscan

Maintainers

Details