SocialCrawl
Unified schema

Place schema

The unified SocialCrawl place or business schema. Every field, its type, per-platform availability, and a machine-readable JSON Schema, generated from the canonical Zod source.

Every SocialCrawl endpoint that returns a place or business gives you this exact shape, whatever the source platform. Write your parser once and the same code reads place data from every platform below. That is the unified schema: one contract instead of a dozen raw upstream formats.

Field reference

FieldTypeNullableDescription
idstringNoPlace ID (Google cid for a business, hotel_identifier for a hotel)
namestringYesBusiness / hotel name
urlstringYesWebsite or canonical URL
categorystringYesPrimary category (e.g. "Coffee shop", "Hotel")
rating.valuenumberYesAverage rating from 0 to the rating max.
rating.maxnumberYesHighest possible rating value, normally 5.
reviews_countnumberYesNumber of ratings
price_levelstringYesPrice band ("inexpensive" / "$$" / null)
addressstringYesStreet address as the source prints it.
phonestringYesPhone number as the source prints it.
latitudenumberYesLatitude in decimal degrees.
longitudenumberYesLongitude in decimal degrees.
verifiedbooleanYesClaimed-business flag (Google is_claimed)
descriptionstringYesDescription of the place.
image_urlsstring or string[]YesImage URL, or a list of image URLs, for the place.
categoriesstring[]YesAdditional categories beyond the primary one.
hotel.starsnumberYesHotel star classification, from 1 to 5.
hotel.stars_descriptionstringYesThe star classification as text, for example '4-star hotel'.
hotel.check_in_timestringYesCheck in time as the hotel prints it.
hotel.check_out_timestringYesCheck out time as the hotel prints it.
hotel.amenitiesobject[]YesAmenities the hotel lists.
hotel.review_topicsobject[]YesTopics guests mention most in reviews.
hotel.pricesobject[]YesPrices offered by booking sites for the hotel.

Extension fields (ext)

Platform-specific passthrough. Each field is present only on the platforms that expose it and is absent everywhere else, so treat every ext.* field as optional. These carry the richer, per-platform signals the unified leaves cannot hold, and the join keys that chain endpoints together.

FieldTypeNullableDescription
ext.distancenumberYesDistance from the searched location, in the source's own unit (miles for Target stores, metres for Naver).
ext.statusstringYesOpen or closed status as the source words it, for example Open.
ext.timezonestringYesIANA timezone of the place, for example America/New_York.
ext.hoursobject[]YesOpening hours by day.
ext.pro_desk_phonestringYes
ext.tool_rental_phonestringYes
ext.place_idstringYesGoogle Maps place id (ChIJ...). place.id holds the cid.
ext.attributes.available_attributesobjectNoAttributes the place has, grouped by kind (for example amenities).
ext.attributes.unavailable_attributesobjectNoAttributes the place lacks, grouped by kind.
ext.rating_distributionobjectYesHow many ratings the place has at each star value, keyed by star from 1 to 5.
ext.people_also_searchobject[]YesOther places people search for alongside this one.
ext.menu_urlstringYesURL of the place's menu.
ext.domainstringYesDomain of the business website, for example www.example.it.
ext.maps_urlstringYesGoogle Maps link for the place, built from its cid.
ext.ranknumberYes1-based position of the place in the result list.
ext.citystringYesCity part of the address as Google publishes it.
ext.postal_codestringYesPostal code part of the address.
ext.regionstringYesRegion part of the address as Google publishes it.
ext.country_codestringYesCountry as an ISO 3166-1 alpha-2 code.
ext.posts_countnumberYes/v1/instagram/location only: the number of public posts Instagram counts at the place.
ext.websitestringYes/v1/instagram/location only: the venue's own website (place.url is its Instagram page).
ext.facebook_places_idstringYes/v1/instagram/location only: the Facebook Places id of the same place.
ext.business_usernamestringYes/v1/instagram/location only: the username of the Instagram business account linked to the place, or null when none is linked.
ext.is_adbooleanYesTrue for a paid 플레이스 광고 slot. Such a row has no organic rank. Naver only.
ext.ad_ranknumberYes1-based position among the paid slots. Naver only.
ext.ad_descriptionstringYesDescription text of a paid slot. Naver only.
ext.status_descriptionstringYesThe line under status, for example the next opening time. Naver only.
ext.visitor_reviews_countnumberYesNumber of visitor reviews. Naver only.
ext.blog_reviews_countnumberYesNumber of blog reviews. Naver only.
ext.booking_urlstringYesURL to book at the place.
ext.keywordsstring[]YesKeywords the place is tagged with. Naver only.
ext.category_ratingsobject[]Yes
ext.room_typestringYes
ext.capacitynumberYes
ext.subtitlestringYes
ext.listing_badgesstring[]Yes
ext.exact_locationbooleanYes
ext.listing_price_notestringYes
ext.host_profile.idstringYes
ext.host_profile.namestringYes
ext.host_profile.avatar_urlstringYes
ext.host_profile.superhostbooleanYes
ext.host_profile.verifiedbooleanYes
ext.host_profile.years_hostingnumberYes
ext.host_profile.months_hostingnumberYes
ext.host_profile.response_ratestringYes
ext.host_profile.response_timestringYes
ext.host_profile.aboutstringYes
ext.host_profile.highlightsstring[]Yes
ext.roomsobject[]Yes
ext.languages_spokenstring[]Yes

Platform availability

13 platforms return the Place shape. id are never null on any platform. The fields below vary: yes means the platform populates it (the value may still be null); a blank means the platform never provides it, so it is always null.

Platformaddresscategoryrating.valuereviews_countimage_urlsphonerating.maxurldescriptionprice_levelcategorieshotel.amenities
Airbnbyesyesyesyesyesyesyesyesyes
Booking.comyesyesyesyesyesyesyes
Googleyesyesyesyesyesyesyesyesyesyesyes
Gumtree
H&Myes
Home Depotyesyesyes
Instagramyesyesyesyesyes
Kohl'syes
Naveryesyesyesyesyesyesyesyesyesyes
Sephorayes
Targetyes
Tripadvisoryesyesyesyesyesyesyesyesyesyesyes
Yelpyesyesyesyes

Machine-readable schema

Validate responses programmatically against the JSON Schema (2020-12):

/schemas/place.json

Point a validator (Ajv, jsonschema, or your framework's) at that URL, or hand it to an agent so it can check the shape without a live call.

Returned by

Endpoints with the Place / PlaceList archetype return this shape:

Airbnb · Booking.com · Google · Gumtree · H&M · Home Depot · Instagram · Kohl's · Naver · Sephora · Target · Tripadvisor · Yelp

See how the same fields map to each platform's raw upstream names in the cross-platform field equivalence table.

On this page