비즈니스 검색
1 크레딧/v1/yelp/searchquery와 location으로 Yelp 비즈니스를 검색합니다. sort(recommended, rating, review_count), ads, cursor는 선택입니다. PlaceList입니다. 표준 티어(1 크레딧)입니다. 제공자가 총건수는 있는데 행이 없으면 호출은 실패하고 환불됩니다.
query, location, sort, ads, cursor
Yelp APIYelp 비즈니스와 리뷰 데이터 API
SocialCrawl API 키로 Yelp 검색, 비즈니스, 고객 리뷰를 구조화 JSON으로 가져옵니다. 공유 장소·리뷰 스키마입니다. 호출은 크레딧으로 과금됩니다.
/v1/yelp
활성 엔드포인트는 5개입니다. 검색, 자동완성, 비즈니스 정보, 리뷰입니다.
- GET /v1/yelp/search
- GET /v1/yelp/search/full
- GET /v1/yelp/search/suggestions
- GET /v1/yelp/business/info
- GET /v1/yelp/business/reviews
Yelp 엔드포인트
Yelp 읽기 엔드포인트는 5개입니다. 검색어와 지역으로 찾고, 자동완성을 받고, encid로 비즈니스를 조회한 뒤 리뷰를 페이지당 10건씩 넘깁니다. 별칭 슬러그는 찾을 수 없습니다.
전체 비즈니스 검색
1 크레딧/v1/yelp/search/full같은 검색을 full-search 경로로 호출합니다. 카드가 더 깁니다. query, location, sort, ads, cursor는 같습니다. 표준 티어(1 크레딧)입니다.
query, location, sort, ads, cursor
검색 제안
1 크레딧/v1/yelp/search/suggestions검색어와 지역에 대한 자동완성 행입니다. 카테고리, 일반, 체인, 비즈니스 제안이 섞입니다. 비즈니스 행의 별칭 URL은 business/info에서 조회되지 않습니다. 표준 티어(1 크레딧)입니다.
query, location
비즈니스 정보
1 크레딧/v1/yelp/business/info22자 encid로 Yelp 비즈니스 하나를 조회합니다. 이름, 반올림하지 않은 별점, 정확한 리뷰 수, 가격대, 주소, 좌표, 카테고리, 사진, 시간대가 담깁니다. 별칭 URL은 404이고 과금되지 않습니다. 표준 티어(1 크레딧)입니다.
id or url
비즈니스 리뷰
5 크레딧/v1/yelp/business/reviews그 encid의 고객 리뷰입니다. 페이지당 10건이고 커서, 사장님 답글, 사진, 언어, HELPFUL 표가 있습니다. 2페이지는 1페이지와 겹치지 않습니다. 고급 티어(5 크레딧)입니다.
id or url, cursor
Yelp API5개 엔드포인트 지원
문서 보기Business
Reviews
Search
22자 encid로 Yelp 비즈니스 하나를 이름, 반올림하지 않은 별점, 리뷰 수, 가격대, 주소, 좌표, 카테고리, 사진, 시간대와 함께 반환합니다.
이미 Yelp encid가 있을 때 사용하세요. 별칭 슬러그는 찾을 수 없습니다. GET /v1/yelp/search로 검색어와 지역으로 비즈니스를 찾습니다.
1크레딧
GET/v1/yelp/business/info?id=zj8Lq1T8KIC5zwFief15jg
$ curl https://www.socialcrawl.dev/v1/yelp/business/info?id=zj8Lq1T8KIC5zwFief15jg \
-H "x-api-key: sc_YOUR_API_KEY"대기 중
// 실제 실행에는 API 키가 필요합니다. "실행해보기"를 누르면 예시 응답을 표시합니다Yelp API 동작
Yelp도 다른 SocialCrawl 데이터 엔드포인트와 같습니다. API 키로 GET /v1/yelp/… 를 호출하고 캐시 미스에 크레딧을 쓰며 동일한 JSON 봉투를 받습니다.
호출 인증
x-api-key 헤더에 키를 보냅니다. 공개 읽기에 Yelp OAuth 앱은 필요 없습니다. SocialCrawl 전 플랫폼에 같은 키를 사용합니다.
GET과 쿼리 파라미터
Yelp 경로는 모두 GET입니다. 검색은 query와 location이 필수이고 sort, ads, cursor는 선택입니다. 정보와 리뷰는 id(encid) 또는 /biz/{encid} URL을 넘깁니다. 과금 전에 형식을 검사합니다.
좌석이 아니라 크레딧
search, search/full, search/suggestions, business/info는 1 크레딧입니다. business/reviews는 5 크레딧입니다. 캐시 히트는 0입니다. 빈 결과나 실패는 환불됩니다.
하나의 JSON 봉투
모든 응답은 같은 모양입니다. success, data, credits_used, credits_remaining, request_id, cached. 리뷰 목록은 다음 페이지가 있으면 next_cursor를 줍니다.
일반적인 연동 순서
도시로 검색한 뒤 encid를 확인하고 리뷰를 페이지합니다.
01검색
GET /v1/yelp/search?query=…&location=…검색어와 지역의 PlaceList
리뷰 크레딧을 쓰기 전에 비즈니스를 찾습니다.
02비즈니스 정보
GET /v1/yelp/business/info?id=…별점, 주소, 좌표, 사진이 있는 Place
리뷰 크레딧을 쓰기 전에 encid를 확인합니다.
03리뷰
GET /v1/yelp/business/reviews?id=…리뷰 10건의 ReviewList
고객 문장과 사장님 답글입니다.
04다음 페이지
GET /v1/yelp/business/reviews?id=…&cursor=…겹치지 않는 다음 10건
이전 페이지의 cursor입니다.
요청
GET /v1/yelp/search?query=Pizza&location=New+York,+NY
Host: www.socialcrawl.dev
x-api-key: sc_your_api_key_here
GET /v1/yelp/business/info?id=zj8Lq1T8KIC5zwFief15jg
GET /v1/yelp/business/reviews?id=zj8Lq1T8KIC5zwFief15jg응답 봉투
{
"success": true,
"data": {
"place": {
"id": "zj8Lq1T8KIC5zwFief15jg",
"name": "Prince Street Pizza",
"rating": { "value": 4.3, "max": 5 },
"reviews_count": 5712
}
},
"credits_used": 1,
"credits_remaining": 9999,
"request_id": "req_…",
"cached": false
}data에 담기는 내용
아키타입에 맞는 필드 이름은 SocialCrawl 전 구간과 같습니다. 한 번 파싱하면 다른 플랫폼에도 재사용합니다.
PlaceListsearch
items[]에 place.id, name, rating, reviews_count, location
Placebusiness/info
id, name, url, rating, reviews_count, price_level, address, coordinates, categories, photos
ReviewListbusiness/reviews
items[]에 text, rating, author, responses[], images, published_at
리뷰 2페이지reviews page 2
next_cursor, 새로운 id 10개, 겹침 없음
게이트웨이 내부
다른 /v1 플랫폼 엔드포인트와 같은 요청 수명주기입니다. Yelp는 별도 서비스가 아닙니다.
- 01
엣지가 호출을 받습니다
Next.js catch-all이 Hono 소셜 API로 넘깁니다. request_id를 만들고 키를 인증한 뒤 분당 600회 한도와 키당 동시 50건을 적용합니다.
- 02
검증 후 차감
레지스트리가 Yelp 리소스를 찾습니다. 필수 파라미터와 형식 검사가 먼저 돕니다. 잘못된 입력은 과금 없이 400입니다. 유효한 호출은 업스트림 작업 전에 티어 비용을 원자적으로 차감합니다.
- 03
캐시 또는 조회
플랫폼 + 리소스 + 파라미터로 캐시 키를 만듭니다. 히트면 즉시 반환하고 credits_used는 0입니다. 미스면 조회하고 5xx/네트워크에서 재시도하며, 소스가 불건전하면 서킷 브레이커가 열립니다.
- 04
정규화 후 반환
업스트림 JSON을 Place, PlaceList, ReviewList로 매핑하고 정규 Zod 스키마로 검증한 뒤 성공 봉투에 넣어 과금 감사 로그를 남깁니다.
운영에서 중요한 과금 규칙
- search, search/full, search/suggestions, business/info: 1 크레딧
- business/reviews: 5 크레딧
- 캐시 히트: 0 크레딧
- 없는 encid: 404, 자동 환불
- 빈 리뷰 페이지: 자동 환불
- 검색이 총건수만 있고 행이 없음: 502, 자동 환불
- 잘못된 파라미터: 400, 과금 없음
- 잔액 부족: 402, 과금 없음
- 리뷰 페이지 크기는 10건
데이터 수집 방식
Yelp는 공개 읽기 데이터입니다. SocialCrawl 스키마로 정규화하므로 두 번째 벤더 SDK를 배울 필요가 없습니다.
이 API에서 Yelp가 의미하는 것
지역 비즈니스 검색, 공개 프로필, 그 비즈니스에 대한 고객 리뷰입니다.
SocialCrawl이 가져오는 방법
검색, 자동완성, 비즈니스, 리뷰 읽기는 일반 GET입니다. 상세 식별자는 22자 encid입니다.
엣지에서 나가는 것
검색은 PlaceList, 비즈니스는 Place, 리뷰는 ReviewList입니다.
지금 제공하지 않는 것
반경 검색, 메뉴, Q&A는 없습니다. 별칭 슬러그는 business/info에서 찾을 수 없습니다.
필드 매핑
search hit→ place.*검색 결과가 place.*
Yelp business→ place.*encid가 place.id
review body→ ReviewList items[]별점, 본문, 사장님 답글
cursor→ query control커서가 리뷰 10건을 페이지
이 API의 활용 분야
이 API가 가장 자주 쓰이는 작업입니다.
5active Yelp endpoints in the registry
1 / 5business/info와 reviews의 크레딧 계단
지역 비즈니스 평판과 리뷰 분석
호출자는 도시로 검색한 뒤 encid를 확인하고 리뷰를 페이지합니다. Tripadvisor와 같은 스키마로 Yelp 검색, Place, ReviewList를 encid 기준으로 조회합니다. 1크레딧 조회 다음 5크레딧 리뷰 페이지입니다.
캐시 미스는 정보는 보통 2초 안, 리뷰 페이지는 몇 초입니다.
활용 사례
팀이 이 데이터를 쓰는 흔한 방식과 그때 쓰는 스택입니다.
로컬 SEO
Python, Sheetsbusiness/info로 별점과 리뷰 수를 보고, reviews로 최근 문장을 봅니다.
VoC 리서치
Node, 노트북커서로 리뷰를 페이지하고 사장님 답글을 남깁니다.
경쟁 인텔
BI 적재식당 세트에 Tripadvisor와 같은 Place 스키마를 씁니다.
두 줄로 호출
검색과 정보는 1 크레딧입니다. 리뷰는 5 크레딧입니다. 캐시 히트는 무료입니다.
curl "https://www.socialcrawl.dev/v1/yelp/search?query=Pizza&location=New+York,+NY" \
-H "x-api-key: sc_your_api_key_here"curl "https://www.socialcrawl.dev/v1/yelp/business/info?id=zj8Lq1T8KIC5zwFief15jg" \
-H "x-api-key: sc_your_api_key_here"curl "https://www.socialcrawl.dev/v1/yelp/business/reviews?id=zj8Lq1T8KIC5zwFief15jg" \
-H "x-api-key: sc_your_api_key_here"엔드포인트
Yelp API는 어떤 데이터를 돌려주나요
모든 엔드포인트가 같은 응답 구조의 JSON을 보내드려요. 엔드포인트가 해당 지표를 지원하고 계산에 필요한 원본 값이 있을 때만 참여율·콘텐츠 카테고리 같은 계산 필드가 포함돼요.
자주 묻는 질문
자주 묻는 질문
API, 요금제, 기능에 대한 질문과 답변입니다.
문의하기Yelp API 비용은 얼마인가요?
Yelp 엔드포인트는 호출한 만큼 크레딧으로 계산해요. 스탠다드 1크레딧, 어드밴스드 5크레딧, 프리미엄 10크레딧이고, Yelp에서는 호출당 1~5크레딧이에요. 가입하면 100크레딧을 무료로 드리고, 구독 없이 쓴 만큼만 내면 돼요.
Yelp 데이터 스크래핑, 법적으로 괜찮을까요?
SocialCrawl은 누구나 볼 수 있는 공개 Yelp 데이터만 돌려드리고, 로그인이 필요한 비공개 콘텐츠에는 접근하지 않아요. 다만 실제 적법성은 활용 목적과 국가별 법률에 따라 달라져요. Yelp 이용약관과 GDPR·CCPA 같은 개인정보 보호 법규를 지키는 책임은 이용자에게 있어요. 이 답변은 일반 안내일 뿐, 법률 자문은 아니에요.
Yelp 스크래핑 API와 공식 Yelp API는 뭐가 다른가요?
SocialCrawl은 앱 심사나 승인 대기가 없어요. 가입 직후 x-api-key 하나로 Yelp 엔드포인트를 바로 호출할 수 있고, 응답은 다른 모든 플랫폼과 같은 통합 스키마로 와요. 요금도 플랫폼별 쿼터 대신 크레딧으로 계산해요. 글 게시 같은 쓰기 작업이 필요하다면 공식 API가 맞아요. SocialCrawl은 읽기 전용 데이터만 다뤄요.