SocialCrawl API 키 하나로 Goodreads의 도서, 독자 리뷰, 저자, 인용구, 시리즈, Listopia 목록을 구조화 JSON으로 가져옵니다. 리뷰는 공통 Review 스키마를 사용합니다. 호출은 크레딧으로 과금됩니다.
활성 엔드포인트는 10개입니다. 도서, 리뷰, 저자, 인용구, 목록을 지원합니다.
공개 Goodreads 데이터를 읽는 엔드포인트는 10개입니다. 도서 검색, 도서 상세, 독자 리뷰 페이지 조회, 판본 목록, 저자 조회, 인용구와 시리즈와 Listopia 목록을 지원합니다.
/v1/goodreads/book도서 한 권을 전체 정보로 반환합니다. 제목, 저자와 역할, 시리즈와 순서, 설명, 장르, 평균 평점과 1점부터 5점까지의 분포, 평점 수와 리뷰 수, 언어별 리뷰 수, 판본 형식, 쪽수, 출판사, ISBN과 ASIN, 수상 내역, 등장인물, 읽고 있는 독자 수와 읽고 싶은 독자 수가 포함됩니다. 표준 티어(1 크레딧)입니다.
id, url, isbn, include_similar, include_lists, include_preview
/v1/goodreads/book/reviews도서의 독자 리뷰를 페이지당 30개 반환하며 popular, newest, oldest 정렬을 지원합니다. 별점 하나, 언어 하나, 특정 문구로 거를 수 있습니다. 리뷰마다 5점 만점 평점, 본문, 날짜, 도움이 됨 수, 리뷰 수가 있는 작성자가 포함됩니다. 고급 티어(5 크레딧)입니다.
id, url, isbn, sort, rating, language, search, limit, cursor
/v1/goodreads/review/comments리뷰 하나 아래에 독자가 남긴 댓글을 본문, 날짜, 작성자와 함께 반환합니다. id는 도서 리뷰 경로의 review.id에서 가져옵니다. 표준 티어(1 크레딧)입니다.
id, limit, cursor
/v1/goodreads/book/editions도서의 모든 판본을 반환합니다. 판본마다 형식, 쪽수, 출판사, 출간일, 언어, ISBN, ISBN-13, ASIN이 포함됩니다. 표준 티어(1 크레딧)입니다.
id, url, isbn, limit, cursor
/v1/goodreads/search제목, 저자, 키워드에 맞는 도서를 반환합니다. 저자, 평균 평점, 평점 수와 리뷰 수, 최초 출간 연도, 쪽수, 시리즈가 포함됩니다. 표준 티어(1 크레딧)입니다.
query, limit, cursor
/v1/goodreads/author저자 한 명을 반환합니다. 이름, 사진, 약력, 팔로워 수, 작품 수, 출생지, 웹사이트가 포함됩니다. 표준 티어(1 크레딧)입니다.
id, url
/v1/goodreads/author/books저자의 도서를 평균 평점, 평점 수와 리뷰 수, 최초 출간 연도, 판본 수와 함께 반환합니다. popular, title, newest, rating, pages 정렬을 지원합니다. 표준 티어(1 크레딧)입니다.
id, url, sort, limit, cursor
/v1/goodreads/quotes도서 하나, 저자 한 명, 태그 하나, 키워드에 맞는 인용구를 반환합니다. 인용구마다 본문, 저자, 도서, 태그, 좋아요 수가 포함됩니다. book, author, tag, query 중 정확히 하나를 보냅니다. 표준 티어(1 크레딧)입니다.
book, author, tag, query, limit, cursor
/v1/goodreads/series시리즈 하나의 도서를 읽는 순서대로 반환합니다. 도서마다 순서, 평점, 집계 수가 있고 시리즈 제목과 설명이 함께 옵니다. 시리즈는 호출 한 번에 전체가 반환됩니다. 표준 티어(1 크레딧)입니다.
id, url
/v1/goodreads/listsid 또는 url을 보내면 Listopia 목록 하나의 도서를 순위, 점수, 투표 수와 함께 반환합니다. tag를 보내면 해당 태그의 목록을 도서 수와 투표자 수와 함께 반환합니다. 표준 티어(1 크레딧)입니다.
id, url, tag, limit, cursor
Goodreads 책 한 권의 제목, 저자, 시리즈, 소개글, 장르, 별점 분포가 있는 평균 평점, 각종 수치, 판본 정보, 수상 내역, 현재 독자 수를 반환합니다.
책 하나를 파악할 때 사용하세요. 독자 평점, 지금 읽는 사람 수, 지금 보는 판본이 어떤 것인지 알 수 있습니다.
1크레딧
$ curl https://www.socialcrawl.dev/v1/goodreads/book?id=5907 \
-H "x-api-key: sc_YOUR_API_KEY"// 실제 실행에는 API 키가 필요합니다. "실행해보기"를 누르면 예시 응답을 표시합니다Goodreads도 다른 SocialCrawl 데이터 엔드포인트와 같습니다. API 키로 GET /v1/goodreads/… 를 호출하고 캐시 미스에 크레딧을 쓰며 동일한 JSON 봉투를 받습니다.
x-api-key 헤더에 키를 보냅니다. 공개 읽기에 Goodreads 계정이나 개발자 앱은 필요 없습니다. SocialCrawl 전 플랫폼에 같은 키를 사용합니다.
도서는 id, url, isbn 중 하나를 받습니다. 저자는 id 또는 url을 받습니다. 검색은 query를 받습니다. 과금 전에 형식을 검증합니다.
도서 리뷰는 5 크레딧입니다. 나머지 Goodreads 경로는 1 크레딧입니다. 캐시 히트는 0입니다.
응답 형태는 success, data, credits_used, credits_remaining, request_id, cached로 동일합니다. 페이지가 있는 목록 응답은 페이지네이션 필드를 가집니다.
대부분 제품은 대상을 먼저 찾은 뒤 필요할 때만 상세와 리뷰를 깊게 봅니다.
GET /v1/goodreads/search?query=…제목, 저자, 키워드에 맞는 도서
검색은 다른 경로가 받는 도서 id를 반환합니다.
GET /v1/goodreads/book?id=…평점 분포, 집계 수, 판본 정보, 장르
호출 한 번으로 평균 평점과 1점부터 5점까지의 분포, 언어별 리뷰 수를 얻습니다.
GET /v1/goodreads/book/reviews?id=…평점과 언어 필터가 있는 페이지당 30개 ReviewList
별점 하나나 언어 하나로 거른 뒤 커서로 다음 페이지를 읽습니다.
GET /v1/goodreads/author/books?id=…인기순 또는 날짜순 저자 도서
같은 저자의 다른 도서가 어떤 평가를 받는지 비교합니다.
GET /v1/goodreads/search?query=the+hobbit
Host: www.socialcrawl.dev
x-api-key: sc_your_api_key_here
GET /v1/goodreads/book/reviews?id=5907&sort=newest{
"success": true,
"data": {
"items": [
{
"review": {
"rating": 5,
"text": "Example review text",
"helpful_votes": 12,
"language": "en"
}
}
]
},
"credits_used": 5,
"credits_remaining": 9999,
"request_id": "req_…",
"cached": false
}아키타입이 맞는 범위에서 필드 이름은 SocialCrawl 나머지와 같습니다. 한 번 파싱해 여러 플랫폼에 재사용합니다.
제목, 저자, 평균 평점, 평점 수와 리뷰 수, 최초 출간 연도
items[]에 평점, 본문, 날짜, helpful_votes, 작성자
items[]에 본문, 날짜, 작성자
이름, 사진, 약력, 팔로워 수, 작품 수, 출생지
다른 /v1 플랫폼 엔드포인트와 같은 요청 수명주기입니다. Goodreads은 사이드카가 아닙니다.
Next.js catch-all이 Hono 소셜 API로 라우팅합니다. request_id를 만들고 키를 인증한 뒤 분당 600회, 키당 동시 50개 한도를 적용합니다.
레지스트리에서 goodreads 경로를 찾습니다. 필수 파라미터와 형식 검사를 먼저 합니다. 잘못된 입력은 과금 없이 400입니다. 유효 호출은 읽기를 시작하기 전에 티어 비용을 원자적으로 차감합니다.
platform + resource + params로 캐시 키를 만듭니다. 히트면 credits_used = 0으로 즉시 반환합니다. 미스면 공개 페이지를 실시간으로 읽으며 5xx나 네트워크 오류는 재시도하고 소스가 불안정하면 서킷 브레이커를 사용합니다.
Goodreads 데이터를 Author, ReviewList, CommentList 아키타입으로 매핑하거나 구조화된 분석 행으로 반환하고 검증한 뒤 성공 봉투로 감싸 과금 감사 로그를 남깁니다.
운영에서 중요한 과금 규칙
Goodreads는 공개 읽기 데이터입니다. SocialCrawl 스키마로 정규화하므로 별도 벤더 SDK를 배울 필요가 없습니다.
공개 도서 페이지, 독자 리뷰, 저자 페이지, 인용구, 시리즈, Listopia 목록입니다.
공개 페이지를 요청 시점에 읽어 서버에서 정규화합니다. Goodreads 로그인을 직접 운영할 필요가 없습니다.
독자 텍스트는 ReviewList와 CommentList, 저자는 Author, 도서와 인용구와 시리즈와 목록은 구조화된 행입니다.
서재, 평점 등록, 리뷰 작성, 비공개 독서 데이터는 제공하지 않습니다.
이 API가 가장 많이 사용되는 작업입니다.
도서 반응 분석, 출판 리서치, 독자 언어 수집
호출은 도서 검색에서 시작해 평점 분포, 리뷰, 같은 저자의 다른 도서로 깊어집니다. 별점, 언어, 문구로 거른 독자 리뷰를 공통 Review 스키마로 받으며 30개 한 페이지가 5 크레딧으로 고정입니다.
라이브 미스는 요청 시점에 공개 페이지를 읽습니다. 반복 호출은 캐시에서 0 크레딧으로 응답합니다.
이 데이터를 활용하는 대표적인 방식과 각 방식에서 주로 사용하는 스택입니다.
book과 author/books로 목록 전체의 평점과 리뷰 규모를 비교합니다.
book/reviews의 평점과 언어 필터로 독자 언어를 수집합니다.
lists와 series로 읽는 순서와 유사 도서 기능을 만듭니다.
도서 검색은 1 크레딧입니다. 리뷰 한 페이지는 5 크레딧입니다. 캐시 히트는 무료입니다.
curl "https://www.socialcrawl.dev/v1/goodreads/search?query=the+hobbit" \
-H "x-api-key: sc_your_api_key_here"curl "https://www.socialcrawl.dev/v1/goodreads/book/reviews?id=5907&sort=newest" \
-H "x-api-key: sc_your_api_key_here"모든 엔드포인트가 같은 응답 구조의 JSON을 보내드려요. 엔드포인트가 해당 지표를 지원하고 계산에 필요한 원본 값이 있을 때만 참여율·콘텐츠 카테고리 같은 계산 필드가 포함돼요.
API, 요금제, 기능에 대한 질문과 답변입니다.
문의하기AI에게 SocialCrawl을 물어보세요