seo/guides/INSTALL_RANK_MATH_EXTENDED_PLUGIN.md

# Install Rank Math API Manager Extended - Complete Guide

## What This Plugin Does

This extended version of the Rank Math API Manager plugin adds **GET endpoints** to read Rank Math SEO metadata (the original only had POST for updating).

### New GET Endpoints

```
GET  /wp-json/rank-math-api/v2/get-meta/{post_id}
     → Retrieve Rank Math meta for a single post

GET  /wp-json/rank-math-api/v2/posts?per_page=100&page=1&status=publish
     → Retrieve all posts with their Rank Math meta (paginated)

POST /wp-json/rank-math-api/v2/update-meta
     → Update Rank Math meta (original functionality)
```

---

## Installation

### Option 1: Install from File (Easiest)

**Step 1: Download the Plugin File**

The plugin file is at:
```
/Users/acid/Documents/seo/wordpress-plugins/rank-math-api-manager-extended.php
```

**Step 2: Upload to WordPress**

1. Download the file
2. In WordPress Admin:
   ```
   Plugins → Add New → Upload Plugin
   ```
3. Select file: `rank-math-api-manager-extended.php`
4. Click: **Install Now**
5. Click: **Activate Plugin**

### Option 2: Install Manually via FTP

1. Connect to your server via FTP
2. Navigate to: `/wp-content/plugins/`
3. Create folder: `rank-math-api-manager-extended`
4. Upload `rank-math-api-manager-extended.php` to that folder
5. In WordPress Admin: Plugins → Activate "Rank Math API Manager Extended"

### Option 3: Install via SSH/Command Line

```bash
# SSH into your server
cd /path/to/wordpress/wp-content/plugins/

# Create plugin folder
mkdir rank-math-api-manager-extended

# Upload file (if you have it locally)
# Or create it directly:
cat > rank-math-api-manager-extended/rank-math-api-manager-extended.php << 'EOF'
[Paste the entire plugin code here]
EOF

# Then activate in WordPress Admin
```

---

## Verify Installation

### Step 1: Check Plugin is Activated

In WordPress Admin:
```
Plugins → Installed Plugins
Look for: "Rank Math API Manager Extended"
Status: Should say "Active"
```

### Step 2: Test the GET Endpoint

Run this curl command (replace credentials and domain):

```bash
curl -u "your_username:your_app_password" \
  "https://www.mistergeek.net/wp-json/rank-math-api/v2/posts?per_page=1&status=publish"
```

**You should see:**
```json
[
  {
    "id": 2845,
    "title": "Best VPN Services 2025",
    "slug": "best-vpn-services",
    "url": "https://www.mistergeek.net/best-vpn-services/",
    "status": "publish",
    "rank_math_title": "The Best VPN Services 2025",
    "rank_math_description": "Discover the best VPN services...",
    "rank_math_focus_keyword": "best VPN",
    "rank_math_canonical_url": ""
  }
]
```

If you see this: ✓ **SUCCESS!**

### Step 3: Run Diagnostic

```bash
python scripts/multi_site_seo_analyzer.py --diagnose https://www.mistergeek.net
```

**You should now see:**
```
Available meta fields:
  • rank_math_description: Discover the best VPN...
  • rank_math_title: The Best VPN Services 2025
  • rank_math_focus_keyword: best VPN
```

---

## Available API Endpoints

### 1. GET Single Post Meta

```bash
curl -u "username:password" \
  "https://www.mistergeek.net/wp-json/rank-math-api/v2/get-meta/2845"
```

**Response:**
```json
{
  "post_id": 2845,
  "post_title": "Best VPN Services 2025",
  "post_url": "https://www.mistergeek.net/best-vpn-services/",
  "rank_math_title": "The Best VPN Services 2025",
  "rank_math_description": "Discover the best VPN services...",
  "rank_math_focus_keyword": "best VPN",
  "rank_math_canonical_url": ""
}
```

### 2. GET All Posts (Paginated)

```bash
curl -u "username:password" \
  "https://www.mistergeek.net/wp-json/rank-math-api/v2/posts?per_page=100&page=1&status=publish"
```

**Query Parameters:**
- `per_page` - Number of posts per page (1-100, default: 100)
- `page` - Page number (default: 1)
- `status` - Post status: publish, draft, pending, trash (default: publish)

**Response:** Array of posts with meta fields

### 3. POST Update Meta

```bash
curl -u "username:password" \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{
    "post_id": 2845,
    "rank_math_title": "New Title",
    "rank_math_description": "New description"
  }' \
  "https://www.mistergeek.net/wp-json/rank-math-api/v2/update-meta"
```

---

## Update the SEO Analyzer Script

Now that the plugin is installed, update the script to use the new endpoint:

**File:** `/Users/acid/Documents/seo/scripts/multi_site_seo_analyzer.py`

The script should automatically detect the meta fields from the REST API response. Just run:

```bash
python scripts/multi_site_seo_analyzer.py --include-drafts --top-n 50
```

The meta descriptions will now be fetched from Rank Math!

---

## Install on All 3 Sites

Repeat the same installation steps for:
- [ ] mistergeek.net ← Install here first to test
- [ ] webscroll.fr
- [ ] hellogeek.net

For each site:
1. Upload plugin via WordPress Admin
2. Activate plugin
3. Test with curl command
4. Run diagnostic

---

## Troubleshooting

### "Plugin could not be activated"

**Solutions:**
1. Check PHP syntax: `php -l rank-math-api-manager-extended.php`
2. Ensure `/wp-content/plugins/` folder exists and is writable
3. Check WordPress error log: `/wp-content/debug.log`

### "Endpoint not found" (404)

**Solutions:**
1. Verify plugin is activated
2. Verify correct URL: `/wp-json/rank-math-api/v2/posts` (not v1)
3. Flush WordPress rewrite rules:
   ```
   WordPress Admin → Settings → Permalinks → Save Changes
   ```

### "Unauthorized" (401)

**Solutions:**
1. Verify credentials (username and app password)
2. Verify user has `read_posts` permission (at least Author role)
3. Check if security plugin is blocking REST API

### "No meta fields returned"

**Solutions:**
1. Verify Rank Math SEO is installed and activated
2. Verify posts have Rank Math meta set (check in WordPress editor)
3. Check WordPress database: `wp_postmeta` table has `rank_math_*` entries

---

## Security Notes

This plugin respects WordPress permissions:
- **Read access:** Requires `read_posts` capability (any logged-in user)
- **Write access:** Requires `edit_posts` capability (Author or higher)
- Uses HTTP Basic Auth (same as original)

For production, consider:
- Using HTTPS only (not HTTP)
- Restricting API access by IP in `.htaccess` or security plugin
- Creating a separate API user with limited permissions

---

## Remove Plugin

If you need to uninstall:

1. In WordPress Admin: Plugins → Deactivate "Rank Math API Manager Extended"
2. Delete the plugin folder: `/wp-content/plugins/rank-math-api-manager-extended/`
3. Original Rank Math SEO still works

---

## Next Steps

1. **Install the plugin** on mistergeek.net
2. **Test with curl:**
   ```bash
   curl -u "username:password" \
     "https://www.mistergeek.net/wp-json/rank-math-api/v2/posts?per_page=1"
   ```
3. **Run diagnostic:**
   ```bash
   python scripts/multi_site_seo_analyzer.py --diagnose https://www.mistergeek.net
   ```
4. **Run analyzer:**
   ```bash
   python scripts/multi_site_seo_analyzer.py --include-drafts --top-n 50
   ```
5. **Install on other 2 sites** and repeat

---

## Support

If you encounter issues:
1. Check the troubleshooting section above
2. Verify curl command works (tests plugin directly)
3. Check WordPress debug log: `/wp-content/debug.log`
4. Share the error message and we can debug together

Ready to install? Download the plugin file and upload it! 🚀