Developer Documentation

⚙️ Under the Hood

RankMation SERP API uses a stealth Camoufox web browser engine to simulate real human organic searches. It parses Google search results natively on demand.

By default, the engine hardcodes the &udm=14 URL parameter. This strips away all modern SERP clutter (AI Overviews, featured snippets, Knowledge Graphs, and "People Also Ask" cards), returning the classic "10 Blue Links" directory.

This approach is crucial for AI agents and rank trackers who require the absolute true organic position of a website without interference from layout variations or dynamic AI widgets.

📡 API Endpoint Reference

Execute rank audits programmatically by invoking the endpoint:

Method	Endpoint	Access
POST	/api/search	Public

Payload Options:

Field	Type	Description
query	string	The query string to search on Google. (Required)
gl	string	Two-letter ISO country code. (e.g. us, pk)
hl	string	Two-letter language code. (e.g. en, es)
num	number	Number of results to extract (default: 10)

🖥️ VPS Deployment Guide

To deploy RankMation to your VPS, make sure you install browser dependencies. You can run the application directly using Docker or bare metal using **PM2**.

Method 1: Docker (Recommended)

# 1. Build the Docker image
docker build -t rankmation-serp .

# 2. Run the container on port 3000
docker run -d -p 3000:3000 --name rankmation rankmation-serp

Method 2: Bare Metal with PM2

# 1. Install browser requirements
npm install
npx playwright install-deps firefox

# 2. Start the scraper using PM2
pm2 start "npm start" --name "rankmation-serp"

🐍 Python Agent Script

import requests

url = "http://localhost:3000/api/search"
payload = {
    "query": "artificial intelligence",
    "gl": "us",
    "hl": "en",
    "num": 10
}

response = requests.post(url, json=payload)
data = response.json()

print(f"Total Found: {data.get('totalFound')}")
for result in data.get('results', []):
    print(f"{result['position']}. {result['title']} -> {result['url']}")

🤖 AI Agent Tool Schema

Provide this JSON schema to function-calling LLMs (OpenAI, Gemini, Anthropic) so they can use RankMation natively:

{
  "name": "google_search_udm14",
  "description": "Performs a clean, clutter-free Google Search to retrieve organic ranking results. Returns organic positions, page titles, URLs, and snippets.",
  "parameters": {
    "type": "object",
    "properties": {
      "query": {
        "type": "string",
        "description": "The Google Search keywords."
      },
      "gl": {
        "type": "string",
        "description": "Two-letter country code for geo-targeting."
      },
      "hl": {
        "type": "string",
        "description": "Two-letter language code."
      },
      "num": {
        "type": "integer",
        "description": "Number of results to extract (10, 20, 30, 50, 100)."
      }
    },
    "required": ["query"]
  }
}