{
  "openapi": "3.0.3",
  "info": {
    "title": "Google Search Light API",
    "description": "A lightweight Google Search API that returns structured JSON results. Fast, reliable, and easy to integrate.\n\n**Features:**\n- Organic search results with snippets\n- Related searches (\"People also search for\")\n- Pagination support (up to 200 results)\n- Language and region filtering\n- Date-based filtering\n- Safe search support\n\n**Query Modifiers:**\nUse these in your query for advanced filtering:\n- `filetype:pdf` - Filter by file type\n- `site:reddit.com` - Restrict to domain\n- `\"exact phrase\"` - Match exact phrase\n- `intitle:keyword` - Search in title only",
    "version": "1.0.0",
    "contact": {
      "name": "Scrappa API Support",
      "url": "https://scrappa.co"
    }
  },
  "servers": [
    {
      "url": "https://scrappa.co",
      "description": "Production server"
    }
  ],
  "security": [
    {
      "ApiKeyHeader": []
    },
    {
      "BearerAuth": []
    }
  ],
  "paths": {
    "/api/google/search-light": {
      "get": {
        "tags": ["Search"],
        "summary": "Google Search (Light)",
        "description": "Perform a lightweight Google search. Returns structured JSON results.\n\n**Limitations:**\n- Max 200 results per query (10 pages × 20 results)\n\n**Tip:** Use query modifiers like `filetype:pdf`, `site:reddit.com`, or `\"exact phrase\"` in your query.",
        "operationId": "googleSearchLight",
        "parameters": [
          {
            "name": "query",
            "in": "query",
            "required": true,
            "description": "The search query. Supports Google search operators like `filetype:`, `site:`, `intitle:`, and quoted phrases.",
            "schema": {
              "type": "string",
              "minLength": 1,
              "maxLength": 2048
            },
            "example": "best coffee shops site:yelp.com"
          },
          {
            "name": "num",
            "in": "query",
            "required": false,
            "description": "Number of results per page (1-20)",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 20,
              "default": 10
            }
          },
          {
            "name": "start",
            "in": "query",
            "required": false,
            "description": "Pagination offset (0-170). Use with `num` for pagination.",
            "schema": {
              "type": "integer",
              "minimum": 0,
              "maximum": 170,
              "default": 0
            }
          },
          {
            "name": "hl",
            "in": "query",
            "required": false,
            "description": "Interface language (2-letter code)",
            "schema": {
              "type": "string",
              "pattern": "^[a-z]{2}$",
              "default": "en"
            },
            "example": "en"
          },
          {
            "name": "gl",
            "in": "query",
            "required": false,
            "description": "Geolocation country (2-letter code). Affects result ranking.",
            "schema": {
              "type": "string",
              "pattern": "^[a-z]{2}$"
            },
            "example": "us"
          },
          {
            "name": "lr",
            "in": "query",
            "required": false,
            "description": "Language restrict. Format: `lang_xx` (e.g., `lang_en`)",
            "schema": {
              "type": "string",
              "pattern": "^lang_[a-z]{2}$"
            },
            "example": "lang_en"
          },
          {
            "name": "cr",
            "in": "query",
            "required": false,
            "description": "Country restrict. Format: `countryXX` (e.g., `countryUS`)",
            "schema": {
              "type": "string",
              "pattern": "^country[A-Z]{2}$"
            },
            "example": "countryUS"
          },
          {
            "name": "safe",
            "in": "query",
            "required": false,
            "description": "Safe search setting",
            "schema": {
              "type": "string",
              "enum": ["active", "off"],
              "default": "off"
            }
          },
          {
            "name": "dateRestrict",
            "in": "query",
            "required": false,
            "description": "Restrict results by date. Format: `d[num]`, `w[num]`, `m[num]`, `y[num]` (e.g., `d7` for last 7 days, `m1` for last month)",
            "schema": {
              "type": "string",
              "pattern": "^[dwmy]\\d*$"
            },
            "example": "m1"
          },
          {
            "name": "sort",
            "in": "query",
            "required": false,
            "description": "Sort order for results",
            "schema": {
              "type": "string",
              "enum": ["date", "date:r", "date:d"]
            }
          },
          {
            "name": "filter",
            "in": "query",
            "required": false,
            "description": "Duplicate content filter. 0=disable, 1=enable",
            "schema": {
              "type": "integer",
              "enum": [0, 1]
            }
          },
          {
            "name": "rights",
            "in": "query",
            "required": false,
            "description": "Filter by usage rights (Creative Commons)",
            "schema": {
              "type": "string",
              "enum": ["cc_publicdomain", "cc_attribute", "cc_sharealike", "cc_noncommercial", "cc_nonderived"]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful search response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SearchResponse"
                },
                "example": {
                  "organic_results": [
                    {
                      "position": 1,
                      "title": "Best Coffee Shops in NYC - Yelp",
                      "link": "https://www.yelp.com/search?find_desc=coffee&find_loc=New+York",
                      "displayed_link": "www.yelp.com › search",
                      "snippet": "Top 10 Best Coffee Shops in New York, NY - Blue Bottle Coffee, Stumptown Coffee Roasters, Joe Coffee Company...",
                      "snippet_highlighted_words": ["Coffee Shops", "Coffee"],
                      "thumbnail": null,
                      "rich_snippet": null
                    }
                  ],
                  "people_also_search_for": [
                    "best coffee shops near me",
                    "specialty coffee shops",
                    "coffee shops open late"
                  ],
                  "search_information": {
                    "query_displayed": "best coffee shops site:yelp.com",
                    "total_results": 1250000,
                    "time_taken": 0.45
                  },
                  "pagination": {
                    "current_page": 1,
                    "pages": [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]
                  },
                  "total_results": 1250000
                }
              }
            }
          },
          "400": {
            "description": "Validation error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ValidationError"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized - Invalid or missing API key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "ApiKeyHeader": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-KEY",
        "description": "API key passed in the X-API-KEY header"
      },
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "description": "Bearer token authentication"
      }
    },
    "schemas": {
      "SearchResponse": {
        "type": "object",
        "properties": {
          "organic_results": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/OrganicResult"
            }
          },
          "people_also_search_for": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Related search suggestions"
          },
          "search_information": {
            "$ref": "#/components/schemas/SearchInformation"
          },
          "pagination": {
            "$ref": "#/components/schemas/Pagination"
          },
          "total_results": {
            "type": "integer",
            "description": "Total number of results found. Convenience accessor that mirrors search_information.total_results."
          }
        }
      },
      "OrganicResult": {
        "type": "object",
        "properties": {
          "position": {
            "type": "integer",
            "description": "Position in search results (1-indexed)"
          },
          "title": {
            "type": "string",
            "description": "Page title"
          },
          "link": {
            "type": "string",
            "format": "uri",
            "description": "URL of the result"
          },
          "displayed_link": {
            "type": "string",
            "description": "Formatted display URL"
          },
          "snippet": {
            "type": "string",
            "nullable": true,
            "description": "Text snippet from the page"
          },
          "snippet_highlighted_words": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Keywords highlighted in the snippet"
          },
          "thumbnail": {
            "type": "string",
            "format": "uri",
            "nullable": true,
            "description": "Thumbnail image URL if available"
          },
          "rich_snippet": {
            "type": "object",
            "nullable": true,
            "description": "Rich snippet data (ratings, reviews, etc.)"
          }
        }
      },
      "SearchInformation": {
        "type": "object",
        "properties": {
          "query_displayed": {
            "type": "string",
            "description": "The search query as interpreted"
          },
          "total_results": {
            "type": "integer",
            "description": "Estimated total results"
          },
          "time_taken": {
            "type": "number",
            "format": "float",
            "description": "Search time in seconds"
          }
        }
      },
      "Pagination": {
        "type": "object",
        "properties": {
          "current_page": {
            "type": "integer",
            "description": "Current page number"
          },
          "pages": {
            "type": "array",
            "items": {
              "type": "integer"
            },
            "description": "Available page numbers"
          }
        }
      },
      "Error": {
        "type": "object",
        "properties": {
          "error": {
            "type": "string",
            "description": "Error message"
          },
          "service": {
            "type": "string",
            "description": "Service that generated the error"
          }
        }
      },
      "ValidationError": {
        "type": "object",
        "properties": {
          "message": {
            "type": "string"
          },
          "errors": {
            "type": "object",
            "additionalProperties": {
              "type": "array",
              "items": {
                "type": "string"
              }
            }
          }
        }
      }
    }
  }
}