Yelp APIFetch Yelp search, a business, and its customer reviews as structured JSON with one SocialCrawl API key. Shared place and review schema. Reads are priced in credits.
5 active endpoints. Search, suggestions, business info, then reviews.
Five live read endpoints for Yelp. Search by term and location, autocomplete, look up a business by its encid, then page reviews 10 at a time. Alias slugs are not found.
/v1/yelp/searchSearch Yelp businesses by query and location. Optional sort (recommended, rating, review_count), ads, and cursor. PlaceList. Standard tier (1 credit). If the provider reports a non-zero total with no rows, the call fails and is refunded.
query, location, sort, ads, cursor
/v1/yelp/search/fullSame search on the full-search path, documented to return fuller cards. Same query, location, sort, ads, and cursor. Standard tier (1 credit).
query, location, sort, ads, cursor
/v1/yelp/search/suggestionsTypeahead rows for a query in a location: category, common, chain, and business suggestions. Business rows carry alias URLs, which do not resolve on business/info. Standard tier (1 credit).
query, location
/v1/yelp/business/infoOne Yelp business by 22-character encid. Name, unrounded rating, exact review count, price level, address, coordinates, categories, photos, timezone. Alias URLs return 404 and are not billed. Standard tier (1 credit).
id or url
/v1/yelp/business/reviewsCustomer reviews for that encid. 10 per page with a cursor, owner replies, photos, language, and HELPFUL votes. Page 2 does not overlap page 1. Advanced tier (5 credits).
id or url, cursor
Returns one Yelp business by its 22-character encid: name, unrounded rating, review count, price level, address, coordinates, categories, photos, and timezone.
Use it when you already have a Yelp encid. Alias slugs return not found. GET /v1/yelp/search finds businesses by term and location.
1 credit
$ curl https://www.socialcrawl.dev/v1/yelp/business/info?id=zj8Lq1T8KIC5zwFief15jg \
-H "x-api-key: sc_YOUR_API_KEY"// No example response recorded for this endpoint yet. The endpoint docs cover the response shape and every fieldYelp is a normal SocialCrawl data surface. You call GET /v1/yelp/… with an API key, spend credits on live misses, and get a single JSON envelope back.
Send your key in the x-api-key header. No Yelp OAuth app for public reads. The same key works across SocialCrawl platforms.
Every Yelp route is GET. Search takes query and location, plus optional sort, ads, and cursor. Info and reviews take id (the encid) or a /biz/{encid} URL. We validate formats before charging.
search, search/full, search/suggestions, and business/info cost 1 credit. business/reviews costs 5 credits. Cache hits cost 0. Empty or hard failures refund.
Every response is the same shape: success, data, credits_used, credits_remaining, request_id, cached. Review lists carry next_cursor when another page exists.
Search a city, confirm the encid, then page reviews.
GET /v1/yelp/search?query=…&location=…PlaceList for a query in a location
Finds businesses before you spend on reviews.
GET /v1/yelp/business/info?id=…Place with rating, address, coordinates, photos
Confirms the encid before you spend on reviews.
GET /v1/yelp/business/reviews?id=…ReviewList of 10 reviews
Customer language plus owner replies.
GET /v1/yelp/business/reviews?id=…&cursor=…The next 10 reviews, no overlap
cursor from the previous page.
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
}Field names match the rest of SocialCrawl where archetypes align. Parse once, reuse across platforms.
items[] with place.id, name, rating, reviews_count, location
id, name, url, rating, reviews_count, price_level, address, coordinates, categories, photos
items[] with text, rating, author, responses[], images, published_at
next_cursor, 10 new ids, zero overlap
Same request lifecycle as every other /v1 platform endpoint. Yelp is not a sidecar.
Next.js catch-all routes into the Hono social API. We mint a request_id, authenticate the key, then enforce rate limit (600/min) and concurrency (50 in flight per key).
Registry lookup finds the Yelp resource. Required params and format checks run first. Invalid input returns 400 with no charge. Valid calls debit the tier cost atomically before upstream work.
A deterministic cache key is built from platform + resource + params. Hit: return immediately, credits_used = 0. Miss: we fetch, retry on 5xx/network, and trip a circuit breaker if the source is unhealthy.
Upstream JSON is mapped to Place, PlaceList, and ReviewList, validated against the canonical Zod schema, then wrapped in the success envelope and logged for billing audit.
Billing rules that matter in production
Yelp is public read data. We normalize it into the SocialCrawl schema so your code does not learn a second vendor SDK.
Public business search, profiles, and customer reviews about a local business.
Search, suggestions, business, and review reads run as ordinary GETs. Detail identity is the 22-character encid.
PlaceList for search, Place for the business, ReviewList for its reviews.
No nearby radius, menus, or Q&A. Alias slugs are not found on business/info.
The jobs this API is most often used for.
Local-business reputation and review mining
Callers search a city, confirm the encid, then page reviews. Yelp search, Place, and ReviewList on the same schema as Tripadvisor, keyed by encid, with a 5-credit review page after 1-credit lookups.
Live misses are typically under two seconds for info and a few seconds for a review page.
Common ways teams put this data to work, and the stack each one tends to run.
business/info for rating and review count, reviews for recent language.
page reviews with cursor and keep owner replies.
same Place schema as Tripadvisor for a restaurant set.
Search and info are 1 credit. Reviews are 5. Cache hits are free.
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"Same key as the rest of the catalog
Every endpoint returns structured JSON in a unified envelope. Computed fields such as engagement rate and content category are included only where the endpoint supports them and the required source inputs are present.
Find answers to frequently asked questions about SocialCrawl's API, pricing, and capabilities.
Contact us