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
| Field | Type | Nullable | Description |
|---|---|---|---|
id | string | No | Place ID (Google cid for a business, hotel_identifier for a hotel) |
name | string | Yes | Business / hotel name |
url | string | Yes | Website or canonical URL |
category | string | Yes | Primary category (e.g. "Coffee shop", "Hotel") |
rating.value | number | Yes | Average rating from 0 to the rating max. |
rating.max | number | Yes | Highest possible rating value, normally 5. |
reviews_count | number | Yes | Number of ratings |
price_level | string | Yes | Price band ("inexpensive" / "$$" / null) |
address | string | Yes | Street address as the source prints it. |
phone | string | Yes | Phone number as the source prints it. |
latitude | number | Yes | Latitude in decimal degrees. |
longitude | number | Yes | Longitude in decimal degrees. |
verified | boolean | Yes | Claimed-business flag (Google is_claimed) |
description | string | Yes | Description of the place. |
image_urls | string or string[] | Yes | Image URL, or a list of image URLs, for the place. |
categories | string[] | Yes | Additional categories beyond the primary one. |
hotel.stars | number | Yes | Hotel star classification, from 1 to 5. |
hotel.stars_description | string | Yes | The star classification as text, for example '4-star hotel'. |
hotel.check_in_time | string | Yes | Check in time as the hotel prints it. |
hotel.check_out_time | string | Yes | Check out time as the hotel prints it. |
hotel.amenities | object[] | Yes | Amenities the hotel lists. |
hotel.review_topics | object[] | Yes | Topics guests mention most in reviews. |
hotel.prices | object[] | Yes | Prices 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.
| Field | Type | Nullable | Description |
|---|---|---|---|
ext.distance | number | Yes | Distance from the searched location, in the source's own unit (miles for Target stores, metres for Naver). |
ext.status | string | Yes | Open or closed status as the source words it, for example Open. |
ext.timezone | string | Yes | IANA timezone of the place, for example America/New_York. |
ext.hours | object[] | Yes | Opening hours by day. |
ext.pro_desk_phone | string | Yes | |
ext.tool_rental_phone | string | Yes | |
ext.place_id | string | Yes | Google Maps place id (ChIJ...). place.id holds the cid. |
ext.attributes.available_attributes | object | No | Attributes the place has, grouped by kind (for example amenities). |
ext.attributes.unavailable_attributes | object | No | Attributes the place lacks, grouped by kind. |
ext.rating_distribution | object | Yes | How many ratings the place has at each star value, keyed by star from 1 to 5. |
ext.people_also_search | object[] | Yes | Other places people search for alongside this one. |
ext.menu_url | string | Yes | URL of the place's menu. |
ext.domain | string | Yes | Domain of the business website, for example www.example.it. |
ext.maps_url | string | Yes | Google Maps link for the place, built from its cid. |
ext.rank | number | Yes | 1-based position of the place in the result list. |
ext.city | string | Yes | City part of the address as Google publishes it. |
ext.postal_code | string | Yes | Postal code part of the address. |
ext.region | string | Yes | Region part of the address as Google publishes it. |
ext.country_code | string | Yes | Country as an ISO 3166-1 alpha-2 code. |
ext.posts_count | number | Yes | /v1/instagram/location only: the number of public posts Instagram counts at the place. |
ext.website | string | Yes | /v1/instagram/location only: the venue's own website (place.url is its Instagram page). |
ext.facebook_places_id | string | Yes | /v1/instagram/location only: the Facebook Places id of the same place. |
ext.business_username | string | Yes | /v1/instagram/location only: the username of the Instagram business account linked to the place, or null when none is linked. |
ext.is_ad | boolean | Yes | True for a paid 플레이스 광고 slot. Such a row has no organic rank. Naver only. |
ext.ad_rank | number | Yes | 1-based position among the paid slots. Naver only. |
ext.ad_description | string | Yes | Description text of a paid slot. Naver only. |
ext.status_description | string | Yes | The line under status, for example the next opening time. Naver only. |
ext.visitor_reviews_count | number | Yes | Number of visitor reviews. Naver only. |
ext.blog_reviews_count | number | Yes | Number of blog reviews. Naver only. |
ext.booking_url | string | Yes | URL to book at the place. |
ext.keywords | string[] | Yes | Keywords the place is tagged with. Naver only. |
ext.category_ratings | object[] | Yes | |
ext.room_type | string | Yes | |
ext.capacity | number | Yes | |
ext.subtitle | string | Yes | |
ext.listing_badges | string[] | Yes | |
ext.exact_location | boolean | Yes | |
ext.listing_price_note | string | Yes | |
ext.host_profile.id | string | Yes | |
ext.host_profile.name | string | Yes | |
ext.host_profile.avatar_url | string | Yes | |
ext.host_profile.superhost | boolean | Yes | |
ext.host_profile.verified | boolean | Yes | |
ext.host_profile.years_hosting | number | Yes | |
ext.host_profile.months_hosting | number | Yes | |
ext.host_profile.response_rate | string | Yes | |
ext.host_profile.response_time | string | Yes | |
ext.host_profile.about | string | Yes | |
ext.host_profile.highlights | string[] | Yes | |
ext.rooms | object[] | Yes | |
ext.languages_spoken | string[] | 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.
| Platform | address | category | rating.value | reviews_count | image_urls | phone | rating.max | url | description | price_level | categories | hotel.amenities |
|---|---|---|---|---|---|---|---|---|---|---|---|---|
| Airbnb | yes | yes | yes | yes | yes | yes | yes | yes | yes | |||
| Booking.com | yes | yes | yes | yes | yes | yes | yes | |||||
| yes | yes | yes | yes | yes | yes | yes | yes | yes | yes | yes | ||
| Gumtree | ||||||||||||
| H&M | yes | |||||||||||
| Home Depot | yes | yes | yes | |||||||||
| yes | yes | yes | yes | yes | ||||||||
| Kohl's | yes | |||||||||||
| Naver | yes | yes | yes | yes | yes | yes | yes | yes | yes | yes | ||
| Sephora | yes | |||||||||||
| Target | yes | |||||||||||
| Tripadvisor | yes | yes | yes | yes | yes | yes | yes | yes | yes | yes | yes | |
| Yelp | yes | yes | yes | yes |
Machine-readable schema
Validate responses programmatically against the JSON Schema (2020-12):
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.
Seller schema
The unified SocialCrawl seller offer schema. Every field, its type, per-platform availability, and a machine-readable JSON Schema, generated from the canonical Zod source.
App schema
The unified SocialCrawl app-store listing schema. Every field, its type, per-platform availability, and a machine-readable JSON Schema, generated from the canonical Zod source.
