{
  "openapi": "3.0.1",
  "info": {
    "title": "Naver Place Reviews + Blog — Korean Review Scraper",
    "description": "Extract visitor reviews, ratings, keywords and visit details from Naver Place, plus blog reviews — with deepBlogSearch, also blog posts beyond Naver's ~100-per-place cap, found by place name. Place URL, ID or keyword input. From the #1 Naver data provider on Apify.",
    "version": "1.1",
    "x-build-id": "7OIb7Zwn9FlIK00wJ"
  },
  "servers": [
    {
      "url": "https://api.apify.com/v2"
    }
  ],
  "paths": {
    "/acts/huggable_quote~naver-place-reviews-scraper/run-sync-get-dataset-items": {
      "post": {
        "operationId": "run-sync-get-dataset-items-huggable_quote-naver-place-reviews-scraper",
        "x-openai-isConsequential": false,
        "summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.",
        "tags": [
          "Run Actor"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/inputSchema"
              }
            }
          }
        },
        "parameters": [
          {
            "name": "token",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Enter your Apify token here"
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    },
    "/acts/huggable_quote~naver-place-reviews-scraper/runs": {
      "post": {
        "operationId": "runs-sync-huggable_quote-naver-place-reviews-scraper",
        "x-openai-isConsequential": false,
        "summary": "Executes an Actor and returns information about the initiated run in response.",
        "tags": [
          "Run Actor"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/inputSchema"
              }
            }
          }
        },
        "parameters": [
          {
            "name": "token",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Enter your Apify token here"
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/runsResponseSchema"
                }
              }
            }
          }
        }
      }
    },
    "/acts/huggable_quote~naver-place-reviews-scraper/run-sync": {
      "post": {
        "operationId": "run-sync-huggable_quote-naver-place-reviews-scraper",
        "x-openai-isConsequential": false,
        "summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.",
        "tags": [
          "Run Actor"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/inputSchema"
              }
            }
          }
        },
        "parameters": [
          {
            "name": "token",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Enter your Apify token here"
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "inputSchema": {
        "type": "object",
        "properties": {
          "placeUrls": {
            "title": "Place URLs or IDs",
            "type": "array",
            "description": "Naver Place URLs or Place IDs. Examples: 'https://map.naver.com/p/entry/place/37234567' or just '37234567'. Short URLs (naver.me) also supported.",
            "items": {
              "type": "string"
            }
          },
          "startUrls": {
            "title": "Start URLs (alternative)",
            "type": "array",
            "description": "Alternative input format: [{\"url\": \"https://map.naver.com/p/entry/place/37234567\"}]. Use placeUrls for simpler input.",
            "items": {
              "type": "object",
              "required": [
                "url"
              ],
              "properties": {
                "url": {
                  "type": "string",
                  "title": "URL of a web page",
                  "format": "uri"
                }
              }
            }
          },
          "searchKeywords": {
            "title": "Search Keywords",
            "type": "array",
            "description": "Business or category names to look up on Naver Place; each match is then scraped for reviews. Examples: ['강남 맛집', '제주 호텔', '강남 미용실']. This searches the business directory — topics, questions or product phrases (e.g. '임신 필수품') match nothing. To target a specific place, use Place URLs instead.",
            "items": {
              "type": "string"
            }
          },
          "maxPlacesPerKeyword": {
            "title": "Max places per keyword",
            "minimum": 1,
            "maximum": 50,
            "type": "integer",
            "description": "Maximum number of places per keyword search",
            "default": 5
          },
          "maxReviews": {
            "title": "Max reviews per place",
            "minimum": 1,
            "maximum": 50000,
            "type": "integer",
            "description": "Maximum number of visitor reviews to collect per place. Overrides maxReviewPages if set. Leave empty for no limit (uses maxReviewPages instead)."
          },
          "maxReviewPages": {
            "title": "Max review pages",
            "minimum": 1,
            "maximum": 1000,
            "type": "integer",
            "description": "Number of visitor review pages to scrape per place (50 reviews per page). Set to 1 for 50 reviews, 10 for 500, etc. Ignored if maxReviews is set.",
            "default": 1
          },
          "visitedSince": {
            "title": "Only reviews of visits since",
            "type": "string",
            "description": "Keep visitor reviews whose VISIT date is on or after this day (e.g. 2026-09-01) — Naver lists reviews by visit date, so the run stops as soon as it reaches older visits. Without Max reviews, every review since that date is collected. A review written today about an older visit is left out; for scheduled runs that should catch every new review, use 'Skip reviews delivered by earlier runs' instead."
          },
          "reviewSort": {
            "title": "Review sort order",
            "enum": [
              "NEWEST",
              "RANKING"
            ],
            "type": "string",
            "description": "Requested sort order for visitor reviews. Naver's review API currently ignores this — every value returns the same newest-first order — so it is kept only so existing tasks keep working. Use maxReviews to control how much you collect.",
            "default": "NEWEST"
          },
          "includeVisitorReviews": {
            "title": "Include visitor reviews",
            "type": "boolean",
            "description": "Scrape visitor reviews (방문자 리뷰). Turn off for blog-only runs, or — with blog reviews also off — a stats-only run that returns just one statistics row per place.",
            "default": true
          },
          "includeBlogReviews": {
            "title": "Include blog reviews",
            "type": "boolean",
            "description": "Also scrape blog reviews (Naver Blog posts linked to the place)",
            "default": true
          },
          "maxBlogReviewPages": {
            "title": "Max blog review pages",
            "minimum": 1,
            "maximum": 100,
            "type": "integer",
            "description": "Number of blog review pages per place (10 items per page). Server limits to ~100 items total.",
            "default": 10
          },
          "deepBlogSearch": {
            "title": "Also find blog posts by place name",
            "type": "boolean",
            "description": "Naver lists only about 100 blog posts on a place (often fewer, sometimes none). This also searches Naver Blog for the place's name, newest first, and adds posts that name the place in their title or excerpt — every word of the name must appear, so other branches of a chain and unrelated posts are left out. Each row's blogMatch says 'place' (listed on the place) or 'name' (found by name search), so you can keep only the exact ones. Names too short to search reliably (fewer than 4 characters, e.g. '문의원') are skipped. Name-search posts are charged like any other row.",
            "default": false
          },
          "maxDeepBlogPosts": {
            "title": "Max blog posts by name search (per place)",
            "minimum": 1,
            "maximum": 1000,
            "type": "integer",
            "description": "With 'Also find blog posts by place name': how many name-search posts to add per place, on top of the place's own blog posts.",
            "default": 30
          },
          "includeReviewPhotos": {
            "title": "Include review photos",
            "type": "boolean",
            "description": "Include photo URLs attached to each visitor review",
            "default": false
          },
          "onlyPhotoReviews": {
            "title": "Only reviews with photos",
            "type": "boolean",
            "description": "Return only visitor reviews that have photos or videos (Naver's own photo-review filter, so text-only reviews are never fetched or charged). maxReviews / visitedSince then count photo reviews. Turn on 'Include review photos' to get the photo URLs. Blog reviews are not affected.",
            "default": false
          },
          "includeReviewStats": {
            "title": "Include review statistics",
            "type": "boolean",
            "description": "Add one statistics row per place (one dataset item): total reviews, average rating, and Naver's place-wide star distribution, review themes, most-mentioned menus and voted keywords — plus the same histograms over just the reviews this run scraped.",
            "default": true
          },
          "maxConcurrency": {
            "title": "Max concurrent places",
            "minimum": 1,
            "maximum": 10,
            "type": "integer",
            "description": "How many places to scrape in parallel. Higher = faster for multi-place runs, but increases rate-limit risk when no proxy is used. Use a proxy for high concurrency.",
            "default": 5
          },
          "onlyNewReviews": {
            "title": "Skip reviews delivered by earlier runs",
            "type": "boolean",
            "description": "For scheduled or repeated runs: reviews an earlier run with this option already returned are skipped — not returned and not charged again. The run looks at the same newest reviews as usual (maxReviews / pages; see the re-check window below for a wider one), so a re-run with nothing new returns 0 items. History is kept per place in a key-value store in your account.",
            "default": false
          },
          "newReviewLookbackDays": {
            "title": "New reviews: re-check window (days)",
            "minimum": 1,
            "maximum": 365,
            "type": "integer",
            "description": "Optional, with 'Skip reviews delivered by earlier runs'. Instead of only the newest maxReviews, read every review visited from N days before this place's previous run up to now, and return the ones not delivered yet (maxReviews then caps the new ones per place). Catches days with more new reviews than maxReviews, and reviews written late about a recent visit. The first run for a place uses the usual window and becomes the starting point. Larger N reads more pages per run (no extra charge — only returned reviews are charged). Empty = off."
          },
          "reviewHistoryName": {
            "title": "Review history name",
            "type": "string",
            "description": "Name of the key-value store that remembers delivered reviews (lowercase letters, digits and '-'). Use different names to keep separate histories for separate pipelines; delete the store or change the name to start over. Default: naver-place-reviews-seen."
          },
          "excludeReviewIds": {
            "title": "Review IDs to skip",
            "type": "array",
            "description": "Reviews you already have, so they are not returned or charged again: visitor reviewId values and/or blog blogUrl values from earlier output. For pipelines that keep their own database instead of using onlyNewReviews' history store — the two can be combined.",
            "items": {
              "type": "string"
            }
          },
          "proxyConfiguration": {
            "title": "Proxy configuration",
            "type": "object",
            "description": "Proxy settings. Recommended to avoid rate limiting."
          }
        }
      },
      "runsResponseSchema": {
        "type": "object",
        "properties": {
          "data": {
            "type": "object",
            "properties": {
              "id": {
                "type": "string"
              },
              "actId": {
                "type": "string"
              },
              "userId": {
                "type": "string"
              },
              "startedAt": {
                "type": "string",
                "format": "date-time",
                "example": "2025-01-08T00:00:00.000Z"
              },
              "finishedAt": {
                "type": "string",
                "format": "date-time",
                "example": "2025-01-08T00:00:00.000Z"
              },
              "status": {
                "type": "string",
                "example": "READY"
              },
              "meta": {
                "type": "object",
                "properties": {
                  "origin": {
                    "type": "string",
                    "example": "API"
                  },
                  "userAgent": {
                    "type": "string"
                  }
                }
              },
              "stats": {
                "type": "object",
                "properties": {
                  "inputBodyLen": {
                    "type": "integer",
                    "example": 2000
                  },
                  "rebootCount": {
                    "type": "integer",
                    "example": 0
                  },
                  "restartCount": {
                    "type": "integer",
                    "example": 0
                  },
                  "resurrectCount": {
                    "type": "integer",
                    "example": 0
                  },
                  "computeUnits": {
                    "type": "integer",
                    "example": 0
                  }
                }
              },
              "options": {
                "type": "object",
                "properties": {
                  "build": {
                    "type": "string",
                    "example": "latest"
                  },
                  "timeoutSecs": {
                    "type": "integer",
                    "example": 300
                  },
                  "memoryMbytes": {
                    "type": "integer",
                    "example": 1024
                  },
                  "diskMbytes": {
                    "type": "integer",
                    "example": 2048
                  }
                }
              },
              "buildId": {
                "type": "string"
              },
              "defaultKeyValueStoreId": {
                "type": "string"
              },
              "defaultDatasetId": {
                "type": "string"
              },
              "defaultRequestQueueId": {
                "type": "string"
              },
              "buildNumber": {
                "type": "string",
                "example": "1.0.0"
              },
              "containerUrl": {
                "type": "string"
              },
              "usage": {
                "type": "object",
                "properties": {
                  "ACTOR_COMPUTE_UNITS": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATASET_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATASET_WRITES": {
                    "type": "integer",
                    "example": 0
                  },
                  "KEY_VALUE_STORE_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "KEY_VALUE_STORE_WRITES": {
                    "type": "integer",
                    "example": 1
                  },
                  "KEY_VALUE_STORE_LISTS": {
                    "type": "integer",
                    "example": 0
                  },
                  "REQUEST_QUEUE_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "REQUEST_QUEUE_WRITES": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATA_TRANSFER_INTERNAL_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATA_TRANSFER_EXTERNAL_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "PROXY_RESIDENTIAL_TRANSFER_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "PROXY_SERPS": {
                    "type": "integer",
                    "example": 0
                  },
                  "PROXY_UNBLOCKER_UNITS": {
                    "type": "integer",
                    "example": 0
                  }
                }
              },
              "usageTotalUsd": {
                "type": "number",
                "example": 0.00005
              },
              "usageUsd": {
                "type": "object",
                "properties": {
                  "ACTOR_COMPUTE_UNITS": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATASET_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATASET_WRITES": {
                    "type": "integer",
                    "example": 0
                  },
                  "KEY_VALUE_STORE_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "KEY_VALUE_STORE_WRITES": {
                    "type": "number",
                    "example": 0.00005
                  },
                  "KEY_VALUE_STORE_LISTS": {
                    "type": "integer",
                    "example": 0
                  },
                  "REQUEST_QUEUE_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "REQUEST_QUEUE_WRITES": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATA_TRANSFER_INTERNAL_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATA_TRANSFER_EXTERNAL_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "PROXY_RESIDENTIAL_TRANSFER_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "PROXY_SERPS": {
                    "type": "integer",
                    "example": 0
                  },
                  "PROXY_UNBLOCKER_UNITS": {
                    "type": "integer",
                    "example": 0
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}