# Kakao Map Scraper — Korea Businesses & Reviews (`muhammadafzal/kakao-map-scraper`) Actor

Scrape Kakao Map businesses and public reviews across Korea, including names, categories, addresses, phones, websites, ratings, hours, and review counts.

- **URL**: https://apify.com/muhammadafzal/kakao-map-scraper.md
- **Developed by:** [Muhammad Afzal](https://apify.com/muhammadafzal) (community)
- **Categories:** Lead generation, Travel
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $24.54 / 1,000 business records

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.
Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

## Kakao Map Scraper — Korea Businesses & Reviews

**Free plan limit:** Free-plan users can receive up to **5 result records per run**. Paid-plan and local/unknown runs retain the Actor's existing limits.

Scrape publicly visible Korean local businesses and Kakao Map visit reviews into structured records for lead research, market mapping, venue analysis, and location intelligence.

### What the Kakao Map Scraper extracts

Each default-dataset item represents one canonical Kakao Map place. Redirected legacy place URLs are resolved to the current place ID, and duplicate canonical places are delivered only once.

| Field | Description |
| --- | --- |
| `placeId` | Canonical Kakao Map place identifier after redirects |
| `name`, `category` | Public business name and Kakao category |
| `address`, `phone`, `website` | Public contact and location details when listed |
| `rating` | Public Kakao visit-review rating when available |
| `reviewCount`, `blogReviewCount` | Public visit-review and blog-review totals |
| `openingHoursText` | Current visible opening-status text |
| `placeUrl` | Canonical `place.map.kakao.com` URL |
| `searchQuery` | Discovery query that produced the business, or `null` for a direct URL |
| `reviews` | Bounded list of public visit reviews, optionally empty |
| `scrapedAt` | ISO timestamp for the extraction |

Each review contains the public author display name, rating, date, text, like count, and a `hasPhotos` flag. Nullable fields remain present as `null`, giving API and agent consumers a stable output shape.

### When to use it

Use keyword discovery to find venues by service and location, such as `서울 카페`, `부산 피부과`, or `Jeju hotel`. Use direct URLs when you already have exact Kakao place pages and need normalized business details or reviews. Typical uses include building Korean local-business lead lists, comparing venue reputation, monitoring public ratings, and enriching a place database with Kakao contact data.

This Actor does not access Kakao accounts, login-only content, reviewer profiles, private data, menu catalogs, photos, or full historical review pagination. `maxReviewsPerBusiness` limits the reviews currently rendered by Kakao; it is not a promise that every historical review will be returned.

### Input

| Input | Type | Default | Purpose |
| --- | --- | --- | --- |
| `searchQueries` | string array | `["서울 카페"]` | Discover places by Korean or English keyword |
| `startUrls` | request list | empty | Scrape exact `https://place.map.kakao.com/PLACE_ID` pages |
| `maxResults` | integer, 1–100 | `10` | Cap businesses across all inputs |
| `includeReviews` | boolean | `true` | Include public visit reviews |
| `maxReviewsPerBusiness` | integer, 0–30 | `10` | Cap visible reviews per business |
| `proxyConfiguration` | object | no proxy | Enable Apify Proxy if Kakao blocks the normal route |

If `startUrls` is non-empty, direct-place mode takes precedence over the default search query. Invalid direct URLs are rejected with an actionable `SUMMARY` instead of silently falling back to a different search.

Keyword example:

```json
{
  "searchQueries": ["서울 카페"],
  "maxResults": 3,
  "includeReviews": true,
  "maxReviewsPerBusiness": 5,
  "proxyConfiguration": { "useApifyProxy": false }
}
```

Direct URL example:

```json
{
  "searchQueries": [],
  "startUrls": [{ "url": "https://place.map.kakao.com/1594748709" }],
  "maxResults": 1,
  "includeReviews": false
}
```

Run it through the API with `POST /v2/acts/muhammadafzal~kakao-map-scraper/runs` and the same JSON body. Results are available from the run’s default dataset; diagnostics are available from the `SUMMARY` record in its default key-value store.

### Example output

```json
{
  "placeId": "1594748709",
  "name": "쎈느",
  "category": "카페",
  "address": "서울 성동구 연무장5길 20 1층 (우)04782",
  "phone": "02-468-2122",
  "website": "https://sceneseoul.com",
  "rating": 3.8,
  "reviewCount": 132,
  "blogReviewCount": 160,
  "openingHoursText": "영업 중 22:00 까지",
  "placeUrl": "https://place.map.kakao.com/1594748709",
  "searchQuery": null,
  "reviews": [
    {
      "author": "J☆",
      "rating": 5,
      "date": "2024.05.27",
      "text": "즐겁게 즐기도록 잘 만들어놨어요",
      "likes": 0,
      "hasPhotos": true
    }
  ],
  "scrapedAt": "2026-09-03T08:48:49.286Z"
}
```

Public values can change between runs. Missing optional data is returned as `null`; reviews are `[]` when disabled or unavailable.

### Pricing

This Actor uses **pay-per-event** pricing. These are the current Apify Store event prices:

| Event | Price (USD) | When it is charged |
|---|---:|---|
| `apify-actor-start` | $0.001 | Actor Start — Charged when the Actor starts running. Number of events charged depends on Actor memory (one event per GB, minimum one event). — Charged once per run. |
| `apify-default-dataset-item` | $0.01 | Business record — One schema-valid Kakao Map business record written to the default dataset. |

Apify platform usage for this Actor run is included alongside the event prices above; no separate per-run platform-usage fee is passed to users.

This covers Apify platform usage for this Actor run. Other Apify products or usage outside this Actor run may still follow your account plan.

### Reliability and diagnostics

The Actor uses a real browser, Korean language headers, conservative concurrency, and a low request rate. It first captures the home-page business details, then opens the review section only when needed. This prevents review navigation from discarding address, phone, website, rating, or count fields. Images, media, and fonts are blocked to reduce bandwidth without removing textual data.

Every completed crawl writes `SUMMARY` with one of these outcomes:

- `DATA`: one or more businesses were delivered.
- `EMPTY`: the valid search returned no public places.
- `BLOCKED_OR_FAILED`: Kakao blocked or failed every requested place; warnings identify affected URLs.
- `REJECTED`: the input contained neither a usable query nor a valid Kakao place URL.

Kakao can change its rendered UI, redirect old place IDs, rate-limit traffic, or present a challenge page. Enable an Apify Proxy configuration if the normal route is blocked. The Actor preserves truthful partial results and never fabricates business records.

### Responsible use

Collect only information Kakao exposes publicly. Follow Kakao’s terms, robots and access policies, applicable Korean privacy law, and your use case’s notice, consent, retention, and deletion obligations. Public reviewer display names may still be personal data: minimize collection, avoid sensitive profiling, and do not use this Actor to collect private, login-only, or sensitive information.

For reproducible support, include the failed run ID, non-secret input, build number, and `SUMMARY` warnings when reporting an issue.

# Actor input Schema

## `searchQueries` (type: `array`):

Use this when discovering businesses by keyword. Enter Korean or English terms, for example \["서울 카페"]. This is not a place URL.

## `startUrls` (type: `array`):

Use this when you already know exact Kakao Map places. Accepts https://place.map.kakao.com/PLACE\_ID URLs; it is not a general web URL.

## `maxResults` (type: `integer`):

Use this to cap delivered business records across all inputs. Enter 1–100; default 10. It does not set the number of reviews.

## `includeReviews` (type: `boolean`):

Use this to embed publicly visible Kakao visit reviews in each business record. Default true; review text can be absent for businesses with no public reviews.

## `maxReviewsPerBusiness` (type: `integer`):

Use this to bound the initially visible public reviews included per business. Enter 0–30; default 10. This does not crawl reviewer profiles.

## `proxyConfiguration` (type: `object`):

Use this when Kakao blocks your network. Residential Korea sessions are recommended for production; no proxy is used by default.

## Actor input object example

```json
{
  "searchQueries": [
    "서울 카페"
  ],
  "startUrls": [],
  "maxResults": 3,
  "includeReviews": true,
  "maxReviewsPerBusiness": 5,
  "proxyConfiguration": {
    "useApifyProxy": false
  }
}
```

# Actor output Schema

## `businesses` (type: `string`):

Schema-valid Kakao Map business records.

## `summary` (type: `string`):

Outcome, counts, and non-sensitive warnings.

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "searchQueries": [
        "서울 카페"
    ],
    "startUrls": [],
    "maxResults": 3,
    "includeReviews": true,
    "maxReviewsPerBusiness": 5
};

// Run the Actor and wait for it to finish
const run = await client.actor("muhammadafzal/kakao-map-scraper").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {
    "searchQueries": ["서울 카페"],
    "startUrls": [],
    "maxResults": 3,
    "includeReviews": True,
    "maxReviewsPerBusiness": 5,
}

# Run the Actor and wait for it to finish
run = client.actor("muhammadafzal/kakao-map-scraper").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "searchQueries": [
    "서울 카페"
  ],
  "startUrls": [],
  "maxResults": 3,
  "includeReviews": true,
  "maxReviewsPerBusiness": 5
}' |
apify call muhammadafzal/kakao-map-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,muhammadafzal/kakao-map-scraper"
        }
    }
}
```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/BLJchUyzKufkoPBqa/builds/qOeyfYRaqaSgjTzrQ/openapi.json