샤오홍슈 마케팅 데이터, 계정·VPN 없이 API로 모으는 법

curl -G "https://www.socialcrawl.dev/v1/xiaohongshu/search" \
  --data-urlencode "query=韩国护肤" --data-urlencode "limit=3" \
  -H "x-api-key: $SOCIALCRAWL_API_KEY"

{
  "success": true,
  "platform": "xiaohongshu",
  "endpoint": "/v1/xiaohongshu/search",
  "data": {
    "items": [
      {
        "post": {
          "id": "<note_id>",
          "url": "https://www.xiaohongshu.com/explore/<note_id>",
          "content": {
            "text": "…(잘린 요약)",
            "media_urls": null,
            "thumbnail_url": "…"
          },
          "author": { "username": "…", "display_name": "…" },
          "engagement": { "views": null, "likes": "<숫자>", "comments": "<숫자>", "shares": 0, "saves": "<숫자>" },
          "ext": { "author_id": "<author_id>", "title": "…", "media_type": "image", "text_truncated": true }
        },
        "computed": { "engagement_rate": null, "language": "zh" }
      }
    ]
  },
  "credits_used": 15,
  "pagination": { "next_cursor": "sc.…", "has_more": true, "page_size": 3 }
}

curl "https://www.socialcrawl.dev/v1/xiaohongshu/trending?limit=10" \
  -H "x-api-key: $SOCIALCRAWL_API_KEY"

curl "https://www.socialcrawl.dev/v1/xiaohongshu/profile?id=<author_id>" \
  -H "x-api-key: $SOCIALCRAWL_API_KEY"

curl "https://www.socialcrawl.dev/v1/xiaohongshu/profile/posts?id=<author_id>&limit=3" \
  -H "x-api-key: $SOCIALCRAWL_API_KEY"

curl "https://www.socialcrawl.dev/v1/xiaohongshu/post?url=https://www.xiaohongshu.com/explore/<note_id>" \
  -H "x-api-key: $SOCIALCRAWL_API_KEY"

curl "https://www.socialcrawl.dev/v1/xiaohongshu/post/comments?url=https://www.xiaohongshu.com/explore/<note_id>&limit=3" \
  -H "x-api-key: $SOCIALCRAWL_API_KEY"

{
  "success": false,
  "error": {
    "type": "RESOURCE_NOT_FOUND",
    "message": "The requested resource was not found on the platform.",
    "status": 404,
    "doc_url": "https://www.socialcrawl.dev/docs/errors#resource-not-found",
    "retryable": false
  },
  "credits_used": 0
}

"""Chain five Xiaohongshu calls: search -> note -> comments -> profile -> creator notes.

Needs: pip install requests, and SOCIALCRAWL_API_KEY in the environment.
Every list row costs 5 credits, so the limits below are the cost dial.
"""
import os
import sys

import requests

BASE = "https://www.socialcrawl.dev/v1/xiaohongshu"
KEYWORD = "防晒"  # sunscreen
SEARCH_LIMIT = 3  # 3 rows x 5 = 15 credits
SMALL_LIMIT = 2   # comments and creator notes, 2 rows x 5 = 10 credits each

key = os.environ.get("SOCIALCRAWL_API_KEY")
if not key:
    sys.exit("Set SOCIALCRAWL_API_KEY first.")

total = 0


def call(path, **params):
    """GET one endpoint. Returns the JSON body, or None on a 404 (0 credits)."""
    global total
    r = requests.get(f"{BASE}/{path}", params=params, headers={"x-api-key": key}, timeout=60)
    if r.status_code == 404:
        body = r.json()
        total += body.get("credits_used", 0)
        print(f"{path}: 404 not found, credits_used={body.get('credits_used')}")
        return None
    r.raise_for_status()
    body = r.json()
    total += body.get("credits_used", 0)
    return body


def need(body, step):
    """Stop the chain cleanly if a step came back empty, reporting what the calls so far cost."""
    if not body:
        sys.exit(f"Stopped at {step}. total credits_used: {total}")
    return body


def page_info(body):
    p = body.get("pagination", {})
    return f"has_more={p.get('has_more')} next_cursor={'yes' if p.get('next_cursor') else 'none'}"


# 1. Search: rows carry a short summary, not the full note.
search = need(call("search", query=KEYWORD, limit=SEARCH_LIMIT), "search")
rows = need(search["data"]["items"], "search (no rows)")
first = rows[0]["post"]
print(f"search: {len(rows)} rows, credits_used={search['credits_used']}, {page_info(search)}")
print(f"  first row: id={first['id']} text_chars={len(first['content']['text'])} "
      f"text_truncated={first['ext']['text_truncated']} views={first['engagement']['views']}")

# 2. The full note, from the first row's URL.
note = need(call("post", url=first["url"]), "note")
post = note["data"]["post"]
author_id = post["ext"]["author_id"]
media = post["content"]["media_urls"]  # a list on image notes, one URL string on video notes
media_count = len(media) if isinstance(media, list) else (1 if media else 0)
print(f"note: credits_used={note['credits_used']} text_chars={len(post['content']['text'])} "
      f"text_truncated={post['ext']['text_truncated']} media_type={post['ext']['media_type']} "
      f"media_urls={type(media).__name__}({media_count}) "
      f"likes={post['engagement']['likes']} shares={post['engagement']['shares']}")

# 3. Top-level comments on that note.
comments = need(call("post/comments", url=first["url"], limit=SMALL_LIMIT), "comments")
print(f"comments: {len(comments['data']['items'])} rows, credits_used={comments['credits_used']}, "
      f"{page_info(comments)}")
for row in comments["data"]["items"]:
    c = row["comment"]
    print(f"  likes={c['engagement']['likes']} replies={c['engagement']['replies']} "
          f"ip_location={c['ext']['ip_location']}")

# 4. The creator, by the author id carried on the note.
profile = need(call("profile", id=author_id), "profile")
a = profile["data"]["author"]
print(f"profile: credits_used={profile['credits_used']} followers={a['followers']} "
      f"posts_count={a['posts_count']} likes_count={a['likes_count']} has_notes_array={'posts' in a}")

# 5. The creator's notes (the profile call does not carry them).
notes = need(call("profile/posts", id=author_id, limit=SMALL_LIMIT), "creator notes")
print(f"creator notes: {len(notes['data']['items'])} rows, credits_used={notes['credits_used']}, "
      f"{page_info(notes)}")
for row in notes["data"]["items"]:
    n = row["post"]
    print(f"  {n['published_at'][:10]} pinned={n['flags']['pinned']} likes={n['engagement']['likes']}")

print(f"total credits_used: {total}")

search: 3 rows, credits_used=15, has_more=True next_cursor=yes
  first row: id=6a5230a30000000021020908 text_chars=60 text_truncated=True views=None
note: credits_used=5 text_chars=500 text_truncated=False media_type=image media_urls=list(7) likes=2383 shares=147
comments: 2 rows, credits_used=10, has_more=True next_cursor=yes
  likes=78 replies=19 ip_location=四川
  likes=0 replies=2 ip_location=河南
profile: credits_used=5 followers=238 posts_count=28 likes_count=15578 has_notes_array=False
creator notes: 2 rows, credits_used=10, has_more=True next_cursor=yes
  2023-09-16 pinned=True likes=9415
  2026-09-01 pinned=False likes=10
total credits_used: 45