{
  "openapi": "3.1.1",
  "info": {
    "title": "Easyparser API",
    "version": "1.0.0",
    "description": "Easyparser is a developer-first API that returns real-time Amazon product data in clean JSON. Retrieve product details, seller offers, and catalog search results with geo-personalization, bulk processing, and robust retry handling.",
    "contact": {
      "name": "Easyparser Support",
      "email": "help@easyparser.com",
      "url": "https://easyparser.gitbook.io/easyparser-documentation/"
    },
    "termsOfService": "https://easyparser.com/policies/terms-service"
  },
  "servers": [
    { "url": "https://realtime.easyparser.com" }
  ],
  "tags": [
    { "name": "Amazon", "description": "Operations for Amazon product data" }
  ],
  "components": {
    "schemas": {
      "Error": {
        "type": "object",
        "properties": {
          "code": { "type": "string", "example": "invalid_parameter" },
          "message": { "type": "string", "example": "Parameter 'keyword' is required for SEARCH operation." },
          "result_id": { "type": "string", "description": "Unique identifier for tracing the request" }
        }
      },
      "Product": {
        "type": "object",
        "properties": {
          "asin": { "type": "string", "example": "B0BS9VVQPD" },
          "title": { "type": "string" },
          "price": { "type": "number", "format": "float", "example": 99.4 },
          "rating": { "type": "number", "format": "float", "example": 4.2 },
          "reviewCount": { "type": "integer", "example": 187 },
          "image": { "type": "string", "format": "uri" },
          "availability": { "type": "string", "example": "In Stock" }
        }
      },
      "SearchItem": {
        "type": "object",
        "properties": {
          "asin": { "type": "string" },
          "title": { "type": "string" },
          "price": { "type": "number", "format": "float" }
        }
      },
      "SearchResponse": {
        "type": "object",
        "properties": {
          "query": { "type": "string" },
          "total": { "type": "integer" },
          "page": { "type": "integer" },
          "results": { "type": "array", "items": { "$ref": "#/components/schemas/SearchItem" } }
        }
      },
      "RequestInfo": {
        "type": "object",
        "properties": {
          "id": { "type": "string" },
          "success": { "type": "boolean" },
          "status_code": { "type": "integer" },
          "credits_used": { "type": "integer" },
          "credits_remaining": { "type": "integer" },
          "credits_reset_at": { "type": "string", "format": "date-time" }
        }
      },
      "RequestParameters": {
        "type": "object",
        "properties": {
          "platform": { "type": "string" },
          "operation": { "type": "string" },
          "output": { "type": "string" },
          "domain": { "type": "string" },
          "keyword": { "type": "string" },
          "include_html": { "type": "string" },
          "exclude_refinements": { "type": "string" }
        }
      },
      "RequestMetadata": {
        "type": "object",
        "properties": {
          "created_at": { "type": "string", "format": "date-time" },
          "processed_at": { "type": "string", "format": "date-time" },
          "total_time_taken": { "type": "number" }
        }
      },
      "ResponseEnvelope": {
        "type": "object",
        "properties": {
          "request_info": { "$ref": "#/components/schemas/RequestInfo" },
          "request_parameters": { "$ref": "#/components/schemas/RequestParameters" },
          "request_metadata": { "$ref": "#/components/schemas/RequestMetadata" },
          "result": {
            "description": "Operation-specific result payload",
            "oneOf": [
              { "$ref": "#/components/schemas/Product" },
              { "$ref": "#/components/schemas/SearchResponse" }
            ]
          }
        },
        "required": ["request_info", "request_parameters", "result"]
      }
    }
  },
  "paths": {
    "/v1/request": {
      "get": {
        "tags": ["Amazon"],
        "summary": "Real-time Amazon data request",
        "description": "Fetch real-time Amazon data. Choose one operation: DETAIL (product detail), OFFER (seller offers), or SEARCH (catalog search). Authentication is done via the api_key query parameter.",
        "operationId": "getRealtimeRequest",
        "x-codeSamples": [
          {
            "lang": "Python",
            "label": "Python Search Example",
            "source": "import requests\nimport json\n\n# set up the request parameters\nparams = {\n  \"api_key\": \"237ae134-ec05-4d3f-a41f-15fbc446f7c5\",\n  \"platform\": \"AMZ\",\n  \"operation\": \"SEARCH\",\n  \"output\": \"json\",\n  \"domain\": \".com\",\n  \"keyword\": \"iphone 17\",\n  \"include_html\": \"false\",\n  \"exclude_refinements\": \"true\",\n}\n\n# make the http GET request to Easyparser API\napi_result = requests.get(\"https://realtime.easyparser.com/v1/request\", params)\n\n# print the JSON response from Easyparser API\nprint(json.dumps(api_result.json()))"
          }
        ],
        "parameters": [
          { 
            "in": "query", 
            "name": "platform", 
            "required": true, 
            "schema": { "type": "string", "enum": ["AMZ"] }, 
            "example": "AMZ",
            "description": "Platform identifier (Amazon)" 
          },
          { 
            "in": "query", 
            "name": "operation", 
            "required": true, 
            "schema": { "type": "string", "enum": ["DETAIL", "OFFER", "SEARCH"] },
            "description": "Type of operation to perform"
          },
          { 
            "in": "query", 
            "name": "output", 
            "required": false, 
            "schema": { "type": "string", "enum": ["json"], "default": "json" }, 
            "example": "json",
            "description": "Response format" 
          },
          { 
            "in": "query", 
            "name": "domain", 
            "required": false, 
            "schema": { "type": "string", "default": ".com" }, 
            "example": ".com",
            "description": "Amazon marketplace domain (.com, .de, .co.uk, etc.)" 
          },
          { 
            "in": "query", 
            "name": "keyword", 
            "required": false, 
            "schema": { "type": "string" }, 
            "example": "iphone 17",
            "description": "Search keyword (required for SEARCH operation)" 
          },
          { 
            "in": "query", 
            "name": "include_html", 
            "required": false, 
            "schema": { "type": "string", "enum": ["true", "false"], "default": "false" }, 
            "example": "false",
            "description": "Whether to include HTML content in response" 
          },
          { 
            "in": "query", 
            "name": "asin", 
            "required": false, 
            "schema": { "type": "string" }, 
            "description": "Amazon ASIN (required for DETAIL or OFFER operations)" 
          },
          { 
            "in": "query", 
            "name": "exclude_refinements", 
            "required": true, 
            "schema": { "type": "string", "enum": ["true"], "default": "true" }, 
            "example": "true",
            "description": "Exclude search refinements from results (required, must be true)" 
          }
        ],
        "responses": {
          "200": {
            "description": "Successful response",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ResponseEnvelope" },
                "examples": {
                  "search_response": {
                    "summary": "Search operation response",
                    "description": "Example response for iPhone 17 search",
                    "value": {
                      "request_info": {
                        "id": "req_12345",
                        "success": true,
                        "status_code": 200,
                        "credits_used": 1,
                        "credits_remaining": 999,
                        "credits_reset_at": "2024-01-01T00:00:00Z"
                      },
                      "request_parameters": {
                        "platform": "AMZ",
                        "operation": "SEARCH",
                        "output": "json",
                        "domain": ".com",
                        "keyword": "iphone 17",
                        "include_html": "false",
                        "exclude_refinements": "true"
                      },
                      "request_metadata": {
                        "created_at": "2024-01-01T12:00:00Z",
                        "processed_at": "2024-01-01T12:00:01Z",
                        "total_time_taken": 1.2
                      },
                      "result": {
                        "query": "iphone 17",
                        "total": 50,
                        "page": 1,
                        "results": [
                          {
                            "asin": "B0BS9VVQPD",
                            "title": "iPhone 17 Pro Max 256GB",
                            "price": 1199.99
                          },
                          {
                            "asin": "B0BS9VVQPE",
                            "title": "iPhone 17 128GB",
                            "price": 999.99
                          }
                        ]
                      }
                    }
                  }
                }
              }
            }
          },
          "400": { 
            "description": "Bad Request", 
            "content": { 
              "application/json": { 
                "schema": { "$ref": "#/components/schemas/Error" },
                "example": {
                  "code": "invalid_parameter",
                  "message": "Parameter 'keyword' is required for SEARCH operation.",
                  "result_id": "req_error_12345"
                }
              } 
            } 
          },
          "401": { 
            "description": "Unauthorized", 
            "content": { 
              "application/json": { 
                "schema": { "$ref": "#/components/schemas/Error" },
                "example": {
                  "code": "unauthorized",
                  "message": "Invalid API key provided.",
                  "result_id": "req_error_12346"
                }
              } 
            } 
          },
          "429": { 
            "description": "Rate limit exceeded", 
            "content": { 
              "application/json": { 
                "schema": { "$ref": "#/components/schemas/Error" },
                "example": {
                  "code": "rate_limit_exceeded",
                  "message": "API rate limit exceeded. Please try again later.",
                  "result_id": "req_error_12347"
                }
              } 
            } 
          },
          "500": { 
            "description": "Server error", 
            "content": { 
              "application/json": { 
                "schema": { "$ref": "#/components/schemas/Error" },
                "example": {
                  "code": "internal_error",
                  "message": "An internal server error occurred.",
                  "result_id": "req_error_12348"
                }
              } 
            } 
          }
        }
      }
    }
  }
}