{
    "openapi": "3.1.0",
    "info": {
        "title": "SerpWiz API",
        "version": "1.0.0",
        "description": "Real-time search results as JSON. $0.15 per 1,000 successful queries; failed requests are free. Rate limits are per account in requests per second. Docs: https://serpwiz.com/docs",
        "contact": {
            "email": "support@serpwiz.com",
            "url": "https://serpwiz.com/docs"
        },
        "termsOfService": "https://serpwiz.com/terms"
    },
    "servers": [
        {
            "url": "https://api.serpwiz.com/v1"
        }
    ],
    "security": [
        {
            "ApiKeyHeader": []
        },
        {
            "BearerAuth": []
        },
        {
            "ApiKeyQuery": []
        }
    ],
    "externalDocs": {
        "url": "https://serpwiz.com/docs",
        "description": "SerpWiz documentation"
    },
    "paths": {
        "/google/search": {
            "get": {
                "operationId": "googleSearch",
                "summary": "Google Search results",
                "description": "One page of live Google web results: organic results, ads, top stories, knowledge panel, People Also Ask, related searches. Costs 1 query on success.",
                "externalDocs": {
                    "url": "https://serpwiz.com/docs/google-search"
                },
                "parameters": [
                    {
                        "name": "q",
                        "in": "query",
                        "required": true,
                        "description": "Search terms (alias: query). Supports Google operators.",
                        "schema": {
                            "type": "string",
                            "maxLength": 2048,
                            "example": "best crm for startups"
                        }
                    },
                    {
                        "name": "gl",
                        "in": "query",
                        "required": false,
                        "description": "2-letter country code to search from.",
                        "schema": {
                            "type": "string",
                            "example": "us"
                        }
                    },
                    {
                        "name": "hl",
                        "in": "query",
                        "required": false,
                        "description": "Interface language code.",
                        "schema": {
                            "type": "string",
                            "example": "en"
                        }
                    },
                    {
                        "name": "page",
                        "in": "query",
                        "required": false,
                        "description": "Results page (10 per page).",
                        "schema": {
                            "type": "integer",
                            "minimum": 1,
                            "maximum": 100,
                            "default": 1
                        }
                    },
                    {
                        "name": "lr",
                        "in": "query",
                        "required": false,
                        "description": "Restrict to a language, e.g. lang_en.",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "cr",
                        "in": "query",
                        "required": false,
                        "description": "Restrict to a country, e.g. countryUS.",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "tbs",
                        "in": "query",
                        "required": false,
                        "description": "Time/verbatim filter: qdr:h|d|w|m|y, li:1, or cdr:1,cd_min:M/D/YYYY,cd_max:M/D/YYYY.",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Search results",
                        "headers": {
                            "X-Credits-Charged": {
                                "description": "Queries deducted for this request.",
                                "schema": {
                                    "type": "integer"
                                }
                            },
                            "X-Credits-Remaining": {
                                "description": "Free allowance plus balance left.",
                                "schema": {
                                    "type": "integer"
                                }
                            },
                            "X-RateLimit-Limit": {
                                "description": "Account requests-per-second limit.",
                                "schema": {
                                    "type": "integer"
                                }
                            },
                            "X-Request-Id": {
                                "description": "Request ID for support.",
                                "schema": {
                                    "type": "string"
                                }
                            }
                        },
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/GoogleSearchResponse"
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Invalid request (free)",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "Missing or invalid API key",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    },
                    "402": {
                        "description": "No credits left",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "Email unverified or account suspended",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    },
                    "429": {
                        "description": "Rate limited (free; see Retry-After)",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    },
                    "502": {
                        "description": "Upstream error (free)",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    },
                    "503": {
                        "description": "Over capacity (free; see Retry-After)",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    },
                    "504": {
                        "description": "Timed out (free)",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/google/maps": {
            "get": {
                "operationId": "googleMaps",
                "summary": "Google Maps places",
                "description": "Places from Google Maps (up to 20 per request). Provide one of q, place_id or url. Costs 1 query on success.",
                "externalDocs": {
                    "url": "https://serpwiz.com/docs/google-maps"
                },
                "parameters": [
                    {
                        "name": "q",
                        "in": "query",
                        "required": false,
                        "description": "What to search for (alias: query).",
                        "schema": {
                            "type": "string",
                            "example": "coffee shops in seattle"
                        }
                    },
                    {
                        "name": "place_id",
                        "in": "query",
                        "required": false,
                        "description": "A Google Place ID.",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "url",
                        "in": "query",
                        "required": false,
                        "description": "A Google Maps URL.",
                        "schema": {
                            "type": "string",
                            "format": "uri"
                        }
                    },
                    {
                        "name": "num",
                        "in": "query",
                        "required": false,
                        "description": "Places to return.",
                        "schema": {
                            "type": "integer",
                            "minimum": 1,
                            "maximum": 20,
                            "default": 10
                        }
                    },
                    {
                        "name": "gl",
                        "in": "query",
                        "required": false,
                        "description": "Country code.",
                        "schema": {
                            "type": "string",
                            "default": "us"
                        }
                    },
                    {
                        "name": "hl",
                        "in": "query",
                        "required": false,
                        "description": "Language code.",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "location",
                        "in": "query",
                        "required": false,
                        "description": "Free-text area, e.g. Toronto, ON.",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "lat",
                        "in": "query",
                        "required": false,
                        "description": "Latitude of search centre.",
                        "schema": {
                            "type": "number",
                            "minimum": -90,
                            "maximum": 90
                        }
                    },
                    {
                        "name": "lng",
                        "in": "query",
                        "required": false,
                        "description": "Longitude of search centre.",
                        "schema": {
                            "type": "number",
                            "minimum": -180,
                            "maximum": 180
                        }
                    },
                    {
                        "name": "zoom",
                        "in": "query",
                        "required": false,
                        "description": "Map zoom.",
                        "schema": {
                            "type": "integer",
                            "minimum": 1,
                            "maximum": 21
                        }
                    },
                    {
                        "name": "radius_km",
                        "in": "query",
                        "required": false,
                        "description": "Radius around lat/lng in km.",
                        "schema": {
                            "type": "number",
                            "exclusiveMinimum": 0,
                            "maximum": 100
                        }
                    },
                    {
                        "name": "place_details",
                        "in": "query",
                        "required": false,
                        "description": "Include full place details (slower).",
                        "schema": {
                            "type": "boolean"
                        }
                    },
                    {
                        "name": "reviews",
                        "in": "query",
                        "required": false,
                        "description": "Include reviews (slower).",
                        "schema": {
                            "type": "boolean"
                        }
                    },
                    {
                        "name": "max_reviews",
                        "in": "query",
                        "required": false,
                        "description": "Max reviews per place.",
                        "schema": {
                            "type": "integer",
                            "minimum": 1,
                            "maximum": 50
                        }
                    },
                    {
                        "name": "images",
                        "in": "query",
                        "required": false,
                        "description": "Include photos (slower).",
                        "schema": {
                            "type": "boolean"
                        }
                    },
                    {
                        "name": "max_images",
                        "in": "query",
                        "required": false,
                        "description": "Max photos per place.",
                        "schema": {
                            "type": "integer",
                            "minimum": 1,
                            "maximum": 20
                        }
                    },
                    {
                        "name": "popular_times",
                        "in": "query",
                        "required": false,
                        "description": "Include popular-times data (slower).",
                        "schema": {
                            "type": "boolean"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Places",
                        "headers": {
                            "X-Credits-Charged": {
                                "description": "Queries deducted for this request.",
                                "schema": {
                                    "type": "integer"
                                }
                            },
                            "X-Credits-Remaining": {
                                "description": "Free allowance plus balance left.",
                                "schema": {
                                    "type": "integer"
                                }
                            },
                            "X-RateLimit-Limit": {
                                "description": "Account requests-per-second limit.",
                                "schema": {
                                    "type": "integer"
                                }
                            },
                            "X-Request-Id": {
                                "description": "Request ID for support.",
                                "schema": {
                                    "type": "string"
                                }
                            }
                        },
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/GoogleMapsResponse"
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Invalid request (free)",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "Missing or invalid API key",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    },
                    "402": {
                        "description": "No credits left",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "Email unverified or account suspended",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    },
                    "429": {
                        "description": "Rate limited (free; see Retry-After)",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    },
                    "502": {
                        "description": "Upstream error (free)",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    },
                    "503": {
                        "description": "Over capacity (free; see Retry-After)",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    },
                    "504": {
                        "description": "Timed out (free)",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/account": {
            "get": {
                "operationId": "getAccount",
                "summary": "Balance, limits and plan",
                "description": "Remaining balance, free allowance, RPS limit and active plan. Free to call.",
                "externalDocs": {
                    "url": "https://serpwiz.com/docs/account"
                },
                "responses": {
                    "200": {
                        "description": "Account",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Account"
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "Missing or invalid API key",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    }
                }
            }
        }
    },
    "components": {
        "securitySchemes": {
            "ApiKeyHeader": {
                "type": "apiKey",
                "in": "header",
                "name": "X-API-Key"
            },
            "BearerAuth": {
                "type": "http",
                "scheme": "bearer"
            },
            "ApiKeyQuery": {
                "type": "apiKey",
                "in": "query",
                "name": "api_key"
            }
        },
        "schemas": {
            "Error": {
                "type": "object",
                "required": [
                    "error"
                ],
                "properties": {
                    "error": {
                        "type": "object",
                        "required": [
                            "status",
                            "code",
                            "message"
                        ],
                        "properties": {
                            "status": {
                                "type": "integer"
                            },
                            "code": {
                                "type": "string",
                                "enum": [
                                    "invalid_request",
                                    "unauthorized",
                                    "insufficient_credits",
                                    "email_unverified",
                                    "account_suspended",
                                    "not_found",
                                    "method_not_allowed",
                                    "rate_limited",
                                    "internal_error",
                                    "upstream_error",
                                    "capacity",
                                    "upstream_timeout",
                                    "unavailable"
                                ]
                            },
                            "message": {
                                "type": "string"
                            },
                            "request_id": {
                                "type": "string"
                            },
                            "docs": {
                                "type": "string",
                                "format": "uri"
                            }
                        }
                    }
                }
            },
            "OrganicResult": {
                "type": "object",
                "properties": {
                    "position": {
                        "type": "integer"
                    },
                    "title": {
                        "type": "string"
                    },
                    "url": {
                        "type": "string",
                        "format": "uri"
                    },
                    "description": {
                        "type": "string"
                    },
                    "date": {
                        "type": "string"
                    }
                },
                "additionalProperties": true
            },
            "GoogleSearchResponse": {
                "type": "object",
                "additionalProperties": true,
                "properties": {
                    "search_term": {
                        "type": "string"
                    },
                    "results": {
                        "type": "array",
                        "items": {
                            "$ref": "#/components/schemas/OrganicResult"
                        }
                    },
                    "ads": {
                        "type": "array",
                        "items": {
                            "type": "object",
                            "additionalProperties": true
                        }
                    },
                    "top_stories": {
                        "type": "array",
                        "items": {
                            "type": "object",
                            "additionalProperties": true
                        }
                    },
                    "knowledge_panel": {
                        "type": "object",
                        "additionalProperties": true
                    },
                    "related_keywords": {
                        "type": "object",
                        "properties": {
                            "spelling_suggestion": {
                                "type": [
                                    "string",
                                    "null"
                                ]
                            },
                            "keywords": {
                                "type": "array",
                                "items": {
                                    "type": "object",
                                    "properties": {
                                        "position": {
                                            "type": "integer"
                                        },
                                        "keyword": {
                                            "type": "string"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "next_page": {
                        "type": "integer"
                    },
                    "next_start": {
                        "type": "integer"
                    }
                }
            },
            "Place": {
                "type": "object",
                "additionalProperties": true,
                "properties": {
                    "position": {
                        "type": "integer"
                    },
                    "title": {
                        "type": "string"
                    },
                    "categoryName": {
                        "type": "string"
                    },
                    "categories": {
                        "type": "array",
                        "items": {
                            "type": "string"
                        }
                    },
                    "address": {
                        "type": "string"
                    },
                    "city": {
                        "type": "string"
                    },
                    "state": {
                        "type": "string"
                    },
                    "postalCode": {
                        "type": "string"
                    },
                    "countryCode": {
                        "type": "string"
                    },
                    "location": {
                        "type": "object",
                        "properties": {
                            "lat": {
                                "type": "number"
                            },
                            "lng": {
                                "type": "number"
                            }
                        }
                    },
                    "rating": {
                        "type": [
                            "number",
                            "null"
                        ]
                    },
                    "reviewsCount": {
                        "type": [
                            "integer",
                            "null"
                        ]
                    },
                    "phone": {
                        "type": [
                            "string",
                            "null"
                        ]
                    },
                    "website": {
                        "type": [
                            "string",
                            "null"
                        ]
                    },
                    "placeId": {
                        "type": "string"
                    },
                    "googleMapsUrl": {
                        "type": "string"
                    },
                    "openingHours": {
                        "type": [
                            "object",
                            "null"
                        ],
                        "additionalProperties": {
                            "type": "string"
                        }
                    }
                }
            },
            "GoogleMapsResponse": {
                "type": "object",
                "required": [
                    "results"
                ],
                "properties": {
                    "results": {
                        "type": "array",
                        "items": {
                            "$ref": "#/components/schemas/Place"
                        }
                    }
                }
            },
            "Account": {
                "type": "object",
                "properties": {
                    "account": {
                        "type": "object",
                        "properties": {
                            "email": {
                                "type": "string"
                            },
                            "rps_limit": {
                                "type": "integer"
                            }
                        }
                    },
                    "credits": {
                        "type": "object",
                        "properties": {
                            "balance": {
                                "type": "integer"
                            },
                            "free_remaining": {
                                "type": "integer"
                            },
                            "free_resets_at": {
                                "type": [
                                    "string",
                                    "null"
                                ],
                                "format": "date-time"
                            },
                            "next_expiry": {
                                "type": [
                                    "object",
                                    "null"
                                ],
                                "properties": {
                                    "queries": {
                                        "type": "integer"
                                    },
                                    "date": {
                                        "type": "string",
                                        "format": "date"
                                    }
                                }
                            }
                        }
                    },
                    "plan": {
                        "type": [
                            "object",
                            "null"
                        ],
                        "properties": {
                            "monthly_usd": {
                                "type": "integer"
                            },
                            "interval": {
                                "type": "string",
                                "enum": [
                                    "month",
                                    "year"
                                ]
                            },
                            "rps": {
                                "type": "integer"
                            },
                            "renews_at": {
                                "type": [
                                    "string",
                                    "null"
                                ],
                                "format": "date-time"
                            }
                        }
                    }
                }
            }
        }
    }
}