Build a WordPress SEO Audit Plugin in 30 Minutes

WordPress is the CMS running 40% or more of the web. Adding a live SEO score widget to the admin dashboard is a useful feature for site owners — and it takes about 30 minutes to build using SEO Score API. Here is a complete walkthrough.

What Are We Building?

A WordPress plugin that adds an SEO Score widget to the admin dashboard. The widget calls SEO Score API once per hour, displays the current score and letter grade, and shows the top 5 issues to fix. Requirements:

• A settings page under Settings → SEO Score to enter your API key
• A dashboard widget registered with wp_dashboard_setup
• One-hour caching using WordPress transients to avoid rate limits
• Score color coding: green (90+), yellow (70-89), red (below 70)
• A link to the full shareable report at seoscoreapi.com/report/{domain}

How Do You Add an SEO Score Widget to the WordPress Admin Dashboard?

Use the wp_add_dashboard_widget() function inside the wp_dashboard_setup action hook. The display callback calls SEO Score API using wp_remote_get() and caches the result with WordPress transients.

The Complete Plugin Code

<?php
/**
 * Plugin Name: SEO Score Checker
 * Description: Shows SEO score for your site using SEO Score API
 * Version: 1.0
 */

// Settings page for API key
add_action('admin_menu', function() {
    add_options_page(
        'SEO Score Settings',
        'SEO Score',
        'manage_options',
        'seo-score',
        'seo_score_settings_page'
    );
});

function seo_score_settings_page() {
    if (isset($_POST['seo_score_api_key'])) {
        update_option('seo_score_api_key',
            sanitize_text_field($_POST['seo_score_api_key']));
        echo '<div class="updated"><p>API key saved.</p></div>';
    }
    $key = get_option('seo_score_api_key', '');
    echo '<div class="wrap">';
    echo '<h1>SEO Score Settings</h1>';
    echo '<form method="post">';
    echo '<p>Get a free API key at ';
    echo '<a href="https://seoscoreapi.com">seoscoreapi.com</a></p>';
    echo '<input type="text" name="seo_score_api_key" ';
    echo 'value="' . esc_attr($key) . '" class="regular-text">';
    echo '<br><br>';
    echo '<input type="submit" class="button-primary" ';
    echo 'value="Save Key">';
    echo '</form></div>';
}

// Dashboard widget
add_action('wp_dashboard_setup', function() {
    wp_add_dashboard_widget(
        'seo_score_widget',
        'SEO Score',
        'seo_score_dashboard_widget'
    );
});

function seo_score_dashboard_widget() {
    $key = get_option('seo_score_api_key');
    if (!$key) {
        echo '<p>Set your API key in Settings → SEO Score</p>';
        return;
    }

    $url = home_url('/');
    $cached = get_transient('seo_score_result');

    if (!$cached) {
        $response = wp_remote_get(
            'https://seoscoreapi.com/audit?url=' . urlencode($url),
            ['headers' => ['X-API-Key' => $key], 'timeout' => 15]
        );

        if (is_wp_error($response)) {
            echo '<p>Could not fetch score.</p>';
            return;
        }

        $cached = json_decode(wp_remote_retrieve_body($response), true);
        set_transient('seo_score_result', $cached, HOUR_IN_SECONDS);
    }

    $score = $cached['score'] ?? 0;
    $grade = $cached['grade'] ?? '?';
    $color = $score >= 90 ? '#22c55e' : ($score >= 70 ? '#eab308' : '#ef4444');

    echo "<div style='text-align:center;padding:1rem'>";
    echo "<div style='font-size:3rem;font-weight:800;color:{$color}'>";
    echo "{$score}</div>";
    echo "<div style='font-size:1.2rem;color:{$color}'>{$grade}</div>";
    echo "<p>{$url}</p>";
    echo "</div>";

    if (!empty($cached['priorities'])) {
        echo '<h4>Top Priorities:</h4><ul>';
        foreach (array_slice($cached['priorities'], 0, 5) as $p) {
            echo "<li><strong>[{$p['severity']}]</strong> ";
            echo esc_html($p['issue']) . "</li>";
        }
        echo '</ul>';
    }

    echo '<p><a href="https://seoscoreapi.com/report/' ;
    echo parse_url($url, PHP_URL_HOST);
    echo '" target="_blank">View Full Report →</a></p>';
}
?>

How Do You Cache SEO API Results in WordPress?

WordPress transients are the right tool for caching external API responses. Call set_transient('seo_score_result', $data, HOUR_IN_SECONDS) to store the result for one hour. On subsequent page loads, get_transient('seo_score_result') returns the cached value instantly, avoiding unnecessary API calls and staying well within the SEO Score API rate limits.

Installation Steps

1. Save the code above as seo-score-checker.php
2. Upload the file to wp-content/plugins/seo-score-checker/ on your server
3. Activate the plugin in WordPress admin under Plugins
4. Go to Settings → SEO Score and enter your free API key from seoscoreapi.com
5. Return to the main Dashboard — the SEO Score widget appears automatically

What WordPress Hook Is Used to Register a Dashboard Widget?

The wp_dashboard_setup action hook fires when the dashboard is being set up. Inside the callback, wp_add_dashboard_widget() registers the widget with a unique ID (seo_score_widget), a display title, and the PHP function that renders the widget content.

Extending the Plugin

This starter plugin covers the dashboard widget. Extensions you could add:

• Show SEO scores in the Posts list table using the manage_posts_columns filter
• Add a score sidebar panel on the post/page edit screen with the block editor API
• Add a bulk scan option under Tools to audit all published posts at once
• Register a cron job with wp_schedule_event() for daily automatic audits
• Send admin email notifications when scores drop below a threshold
• Display SXO, AEO, and AIO sub-scores for Starter plan and above

Frequently Asked Questions

How do you add an SEO score widget to the WordPress admin dashboard?

Use wp_add_dashboard_widget() inside the wp_dashboard_setup action hook. The display callback calls SEO Score API with wp_remote_get(), caches the result with set_transient() for one hour, then renders the score, grade, and top issues.

What WordPress hook is used to register a dashboard widget?

The wp_dashboard_setup action hook fires during dashboard initialization. Add your widget registration inside add_action('wp_dashboard_setup', ...) and call wp_add_dashboard_widget() with a unique ID, a title, and a display callback function.

How do you cache SEO API results in WordPress?

Use WordPress transients: set_transient('seo_score_result', $data, HOUR_IN_SECONDS) stores the result for one hour. On subsequent loads, get_transient() returns the cached value without hitting the API, staying within rate limits.

How do you store an API key securely in a WordPress plugin?

Use update_option() to save the key in the WordPress database after sanitizing with sanitize_text_field(). Retrieve it with get_option(). Use esc_attr() when outputting in HTML attributes to prevent XSS.

How long does it take to build a WordPress SEO audit plugin?

About 30 minutes. The complete plugin is roughly 80 lines of PHP covering the settings page, dashboard widget, API call, and transient cache. No Composer packages or additional dependencies are required.