RankWatch API

A powerful keyword ranking monitoring API built with Val Town. Track your SEO rankings with precision and reliability.

• Keyword Ranking Monitoring: Track Google rankings for unlimited keywords
• Project Management: Organize keywords by website/domain
• Historical Data: Complete ranking history with change tracking
• Real-time Checks: Force immediate ranking checks (unlimited plan)
• Competitor Analysis: See who ranks for your keywords

• JWT Authentication: Secure token-based authentication
• Rate Limiting: SQLite-based rate limiting per user/endpoint
• Soft Deletes: All deletes are reversible
• Global Search: Search across projects, keywords, and rankings
• CSV Export: Export all data types to CSV format
• Bulk Operations: Bulk import/update/delete keywords
• Email Alerts: Automated ranking change notifications

• Freemium: 10 keywords, 1 project, weekly updates
• Unlimited: Unlimited keywords/projects, daily updates

Access interactive documentation at: GET /docs

Get the OpenAPI spec at: GET /docs/openapi.json

ReDoc interface at: GET /docs/redoc

• Runtime: Deno on Val Town
• Framework: Hono for HTTP routing
• Database: SQLite (Turso-powered)
• External API: Serper.dev for Google search data
• Email: Val Town std/email (Resend integration ready)

• main.ts - Main application entry point
• authApi.ts - Authentication endpoints
• projectsApi.ts - Project management
• keywordsApi.ts - Keyword management with bulk operations
• rankingsApi.ts - Ranking data and analysis
• searchApi.ts - Global search functionality
• exportApi.ts - CSV export endpoints
• swaggerApi.ts - API documentation
• serperClient.ts - Serper.dev integration
• cronDaily.ts - Daily ranking checks (unlimited users)
• cronWeekly.ts - Weekly ranking checks (freemium users)

# JWT Secret (generate a secure random string)
JWT_SECRET=your-secure-jwt-secret-key

# Serper.dev API Key (get from https://serper.dev)
SERPER_API_KEY=your-serper-api-key

# Resend API Key (for email notifications)
RESEND_API_KEY=your-resend-api-key

# Optional: Custom base URL
BASE_URL=https://your-custom-domain.com

# Optional: Database URL (for Turso migration)
DATABASE_URL=sqlite://local.db

1. Create Vals: Create separate Vals for each main component:

   • Main API: main.ts
   • Weekly Cron: cronWeekly.ts
   • Daily Cron: cronDaily.ts

2. Configure Environment: Set environment variables in Val Town settings

3. Setup Cron Jobs:

   • Weekly: Monday 9 AM UTC
   • Daily: Every day 6 AM UTC

POST   /auth/register     - Create account
POST   /auth/login        - Login user
GET    /auth/me          - Get user info
POST   /auth/refresh     - Refresh token
POST   /auth/logout      - Logout

GET    /projects          - List projects
POST   /projects          - Create project
GET    /projects/{id}     - Get project
PUT    /projects/{id}     - Update project
DELETE /projects/{id}     - Delete project (soft)
GET    /projects/search   - Search projects

GET    /projects/{id}/keywords     - List keywords
POST   /projects/{id}/keywords     - Add keyword
PUT    /keywords/{id}              - Update keyword
DELETE /keywords/{id}              - Delete keyword (soft)
POST   /keywords/bulk-create       - Bulk add keywords
PUT    /keywords/bulk-update       - Bulk update keywords
DELETE /keywords/bulk-delete       - Bulk delete keywords
GET    /keywords/search            - Search keywords

GET    /keywords/{id}/rankings     - Current ranking
GET    /keywords/{id}/history      - Ranking history
GET    /keywords/{id}/competitors  - Competitor analysis
POST   /keywords/{id}/check-now    - Force check (unlimited)
GET    /projects/{id}/summary      - Project summary

GET    /search                     - Global search
GET    /search/suggestions         - Search autocomplete
GET    /search/recent              - Recent items

GET    /projects/{id}/export       - Export project CSV
GET    /keywords/{id}/export       - Export keyword history CSV
GET    /reports/usage              - Export usage report CSV
GET    /export/all-keywords        - Export all keywords CSV
GET    /export/format-info         - Export format info

• users - User accounts and plans
• projects - Website/domain projects
• keywords - Keywords to track
• rankings - Ranking snapshots
• rank_history - Historical ranking changes
• alerts - Email alert configurations

• rate_limits - API rate limiting
• usage_limits - Plan usage tracking

All authenticated endpoints require:

Authorization: Bearer <jwt_token>

• Freemium: 100 requests/hour per endpoint
• Unlimited: 1000 requests/hour per endpoint

Headers included in responses:

• X-RateLimit-Limit: Request limit
• X-RateLimit-Remaining: Remaining requests
• X-RateLimit-Reset: Reset timestamp

• Position improvements/declines
• Top 10 entry/exit
• Weekly/daily summaries

Configure email settings in config.ts:

resend: {
  apiKey: Deno.env.get("RESEND_API_KEY"),
  fromEmail: "noreply@rankwatch.dev",
}

1. Clone the project to your Val Town workspace
2. Set environment variables in Val Town settings
3. Deploy main API using main.ts
4. Setup cron jobs for automated ranking checks
5. Test endpoints using Swagger UI at /docs

When ready to migrate from Val Town SQLite to Turso:

1. Update DATABASE_URL environment variable
2. Modify connection in database.ts
3. Run database migrations
4. Update backup/restore procedures

Use Swagger UI at /docs for interactive testing

The API includes health checks:

• GET /health - Service health
• GET /status - API status and features
• GET /docs/health - Documentation health

• GET / - API welcome/info
• GET /health - Database connectivity check
• GET /status - Feature and limits overview

• Standardized error responses
• Rate limit headers
• Comprehensive logging
• Admin error notifications

1. Follow existing code patterns
2. Update documentation for new features
3. Test all endpoints thoroughly
4. Ensure rate limiting works correctly

MIT License - Built with ❤️ using Val Town

Need help? Check the Swagger documentation at /docs or contact support.