{
  "openapi": "3.1.0",
  "info": {
    "title": "Ranktracker.id API Gateway",
    "description": "Standardized cloud scraping, local SEO auditing, contact extraction, and GEO AI article writing APIs. Optimized for autonomous AI Agents (LangChain, CrewAI, OpenAI Actions, Custom GPTs).",
    "version": "1.0.0"
  },
  "servers": [
    {
      "url": "https://ranktracker.id",
      "description": "Production Server"
    }
  ],
  "paths": {
    "/api/v1/search": {
      "post": {
        "summary": "Structured Web Search",
        "description": "Performs a localized Google search and returns structured search results designed for LLM prompts.",
        "operationId": "webSearch",
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "query": {
                    "type": "string",
                    "description": "The search query keyword (e.g., 'best coffee shop jakarta')."
                  },
                  "gl": {
                    "type": "string",
                    "default": "id",
                    "description": "Country code filter."
                  },
                  "hl": {
                    "type": "string",
                    "default": "id",
                    "description": "Language code filter."
                  },
                  "maxResults": {
                    "type": "integer",
                    "default": 10,
                    "maximum": 20,
                    "description": "Max organic results to return."
                  }
                },
                "required": [
                  "query"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successful search results",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean"
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "results": {
                          "type": "array",
                          "items": {
                            "type": "object"
                          }
                        }
                      }
                    },
                    "billing": {
                      "type": "object",
                      "properties": {
                        "creditsSpent": {
                          "type": "integer"
                        },
                        "remainingCredits": {
                          "type": "integer"
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/geo/articles": {
      "post": {
        "summary": "GEO AI SEO Article Creator",
        "description": "Generates a highly researched SEO article targeting a specific keyword, optimized for AI Search Engine Overviews.",
        "operationId": "generateGeoArticle",
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "keyword": {
                    "type": "string",
                    "description": "Target keyword for the article."
                  },
                  "language": {
                    "type": "string",
                    "default": "Indonesia",
                    "description": "Language of the output article."
                  },
                  "aiModel": {
                    "type": "string",
                    "default": "Gemini Flash 3.5",
                    "description": "The target model. Transparently routes to DeepSeek fallback behind the scenes."
                  },
                  "wordCount": {
                    "type": "integer",
                    "default": 1000,
                    "description": "Length of the article."
                  },
                  "customInstructions": {
                    "type": "string",
                    "description": "Optional custom tone or format prompts."
                  }
                },
                "required": [
                  "keyword"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successful article generation",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean"
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "keyword": {
                          "type": "string"
                        },
                        "article": {
                          "type": "string",
                          "description": "Clean Markdown article content."
                        },
                        "wordCount": {
                          "type": "integer"
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/maps/scrape": {
      "post": {
        "summary": "Google Maps Scraper",
        "description": "Extracts localized business profiles from Google Maps, including coordinates, phone numbers, and websites.",
        "operationId": "scrapeGoogleMaps",
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "keyword": {
                    "type": "string",
                    "description": "Search query query (e.g. 'bengkel mobil bandung')."
                  },
                  "gl": {
                    "type": "string",
                    "default": "id"
                  },
                  "hl": {
                    "type": "string",
                    "default": "id"
                  },
                  "page": {
                    "type": "integer",
                    "default": 1
                  }
                },
                "required": [
                  "keyword"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successful listings harvest",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean"
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "places": {
                          "type": "array",
                          "items": {
                            "type": "object"
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/maps/email": {
      "post": {
        "summary": "Website Email Extractor",
        "description": "Crawls a business website homepage and contacts page, extracting telephone numbers, emails, and WhatsApp contacts using cloud proxy networks.",
        "operationId": "extractWebsiteContacts",
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "websiteUrl": {
                    "type": "string",
                    "description": "Target website URL (e.g. 'https://bengkelmobil.com')."
                  },
                  "hasPhone": {
                    "type": "boolean",
                    "default": false,
                    "description": "If true, skips phone number extraction to save bandwidth."
                  }
                },
                "required": [
                  "websiteUrl"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Extracted contacts payload",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean"
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "emails": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          }
                        },
                        "phones": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/usage": {
      "get": {
        "summary": "Retrieve Usage Stats",
        "description": "Returns credit balance and recent API Gateway call history log entries.",
        "operationId": "getUsage",
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Usage stats response"
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "http",
        "scheme": "bearer",
        "description": "Authorization token format: Bearer rt_live_YOUR_KEY"
      }
    }
  }
}