igny8/docs/90-REFERENCE/SEED-KEYWORDS-IMPORT-GUIDE.md

Global Keywords Database (SeedKeyword) - Import Guide

Overview

The Global Keywords Database stores canonical keyword suggestions that can be imported into account-specific keywords. These are organized by Industry and Sector.

Admin URL: https://api.igny8.com/admin/igny8_core_auth/seedkeyword/

---

Import Functionality

CSV Format

The import expects a CSV file with the following columns:

Column	Type	Required	Description	Example
keyword	String	Yes	The keyword phrase	"best massage chairs"
industry	String	Yes	Industry name (must exist)	"Health & Wellness"
sector	String	Yes	Sector name (must exist)	"Massage Products"
volume	Integer	No	Monthly search volume	5400
difficulty	Integer	No	Keyword difficulty (0-100)	45
country	String	No	Country code (US, CA, GB, etc.)	"US"
is_active	Boolean	No	Active status	True

Sample CSV

keyword,industry,sector,volume,difficulty,country,is_active
best massage chairs,Health & Wellness,Massage Products,5400,45,US,True
deep tissue massage chair,Health & Wellness,Massage Products,720,52,US,True
shiatsu massage chair,Health & Wellness,Massage Products,1200,48,US,True

Template file available: /data/app/igny8/backend/seed_keywords_import_template.csv

---

How to Import

Step 1: Prepare Your CSV File

1. Download the template: seed_keywords_import_template.csv
2. Add your keywords (one per row)
3. Ensure Industry and Sector names exactly match existing records
4. Save as CSV (UTF-8 encoding)

Step 2: Import via Django Admin

1. Go to: https://api.igny8.com/admin/igny8_core_auth/seedkeyword/
2. Click "Import" button (top right)
3. Click "Choose File" and select your CSV
4. Click "Submit"
5. Review the preview:
   • ✅ Green = New records to be created
   • 🔵 Blue = Existing records to be updated
   • ❌ Red = Errors (fix and re-import)
6. If preview looks good, click "Confirm import"

Step 3: Verify Import

• Check the list to see your imported keywords
• Use filters to find specific industries/sectors
• Edit any records if needed

---

Data Validation

The import process automatically:

✅ Validates volume: Ensures it's a positive integer (defaults to 0 if invalid)
✅ Validates difficulty: Clamps to 0-100 range
✅ Validates country: Must be one of: US, CA, GB, AE, AU, IN, PK (defaults to US)
✅ Handles duplicates: Uses (keyword, industry, sector) as unique key
✅ Skip unchanged: If keyword already exists with same data, it's skipped

---

Bulk Delete

How to Delete Keywords

1. Select keywords using checkboxes (or "Select all")
2. Choose "Delete selected keywords" from the action dropdown
3. Click "Go"
4. Review the confirmation page showing all related objects
5. Click "Yes, I'm sure" to confirm deletion

Note: Only superusers and developers can delete seed keywords.

---

Export Functionality

Export to CSV/Excel

1. Go to: https://api.igny8.com/admin/igny8_core_auth/seedkeyword/
2. (Optional) Use filters to narrow down results
3. Click "Export" button (top right)
4. Choose format: CSV, Excel, JSON, etc.
5. File downloads with all selected fields

Export includes:

• All keyword data
• Related industry/sector names
• SEO metrics (volume, difficulty)
• Metadata (created date, active status)

---

Common Issues & Solutions

Issue: "Industry not found" error during import

Solution:

• Ensure the industry name in your CSV exactly matches an existing Industry record
• Check spelling, capitalization, and spacing
• View existing industries: /admin/igny8_core_auth/industry/

Issue: "Sector not found" error during import

Solution:

• Ensure the sector name in your CSV exactly matches an existing IndustrySector record
• The sector must belong to the specified industry
• View existing sectors: /admin/igny8_core_auth/industrysector/

Issue: Import shows errors for all rows

Solution:

• Check CSV encoding (must be UTF-8)
• Ensure column headers match exactly: keyword,industry,sector,volume,difficulty,country,is_active
• Remove any extra columns or spaces in headers
• Verify there are no special characters causing parsing issues

Issue: Duplicate keyword error

Solution:

• Keywords are unique per (keyword, industry, sector) combination
• If importing a keyword that already exists, it will be updated (not duplicated)
• Use skip_unchanged = True to avoid unnecessary updates

Issue: Delete confirmation page has no "Delete" button

Solution: ✅ FIXED - Custom bulk delete action now includes proper delete button on confirmation page

---

Permissions

Action	Permission Required
View	Staff users
Add	Superuser
Edit	Superuser
Delete	Superuser or Developer
Import	Superuser
Export	Staff users

---

Technical Details

Model Location

• Model: backend/igny8_core/auth/models.py - SeedKeyword
• Admin: backend/igny8_core/auth/admin.py - SeedKeywordAdmin
• Resource: backend/igny8_core/auth/admin.py - SeedKeywordResource

Database Table

• Table name: igny8_seed_keywords
• Unique constraint: (keyword, industry, sector)
• Indexes:
  • keyword
  • industry, sector
  • industry, sector, is_active
  • country

API Access (Read-Only)

• Endpoint: /api/v1/auth/seed-keywords/
• ViewSet: SeedKeywordViewSet (ReadOnlyModelViewSet)
• Filters: industry, sector, country, is_active

---

Related Documentation

• Django Admin Guide
• Models Reference
• Planner Module

---

Last Updated: January 11, 2026
Maintainer: IGNY8 Team