# Place

Schemas

Locations posts are tagged with (venues, landmarks, areas), with their address, coordinates and post count.

## Endpoints

2 endpoints return places on Facebook Marketplace and Instagram.

- [GETFacebook Marketplace Location Search API`/v1/facebook/search_places`](https://socialtap.dev/docs/reference/facebook/search_places/index.md)
- [GETInstagram Location API`/v1/instagram/place`](https://socialtap.dev/docs/reference/instagram/place/index.md)

## Schema

Single-item endpoints return this object as `data`; list endpoints return an array of them as `data` with a [`page`](https://socialtap.dev/docs/pagination/index.md) object. The standard [`meta`](https://socialtap.dev/docs/reference/index.md#meta) comes with every response.

| Field | Type | Description |
| --- | --- | --- |
| `platform` | `string` | Platform ID (tiktok, instagram, …). |
| `id` | `string` | Platform-native place ID (TikTok POI ID, Instagram location ID, Facebook Page ID). |
| `name` | `string` | Place name as the platform shows it. |
| `url` | `string` (uri) | Canonical place page URL. |
| `type` | `string` | Coarse kind: venue for one spot (a business, landmark or address), area for a region (a neighborhood, city, state or country); unknown when the platform does not say. New values may be added; treat unknown values as unknown.<br>One of `venue`, `area`, `unknown` |
| `category` | `string` or `null` | The platform's category label (Cafe, City, Pizza Fast Food), as shown; not normalized across platforms. |
| `description` | `string` or `null` | The place's description or about text; null when none is shown. |
| `address` | `string` or `null` | Address as the platform shows it: a street line on some platforms, the whole postal address or only the enclosing region on others; not normalized. |
| `city` | `string` or `null` | City or locality, as shown. |
| `postal_code` | `string` or `null` | Postal or ZIP code. |
| `country_code` | `string` or `null` | ISO 3166-1 alpha-2 country of the place. |
| `latitude` | `number` or `null` | WGS 84 latitude in degrees; null when the platform does not show coordinates (set together with longitude). |
| `longitude` | `number` or `null` | WGS 84 longitude in degrees; null when the platform does not show coordinates (set together with latitude). |
| `phone` | `string` or `null` | The business's public phone number, as shown; null when none is shown. |
| `website_url` | `string` (uri) or `null` | The place's own website. |
| `price_range` | `integer` or `null` | The business's price range, 1 (inexpensive, $) to 4 (expensive, $$$$); null when the platform shows none. |
| `images` | `object[]` | Pictures of the place the platform shows, in its order; each of type image. \[\] when none (listed in unknown_fields when the source cannot see them). Platform CDN URLs can expire within hours: see expires_at. |
| `images[].type` | `string` | Kind of file. New values may be added; treat unknown values as other.<br>One of `image`, `video`, `audio`, `gif` |
| `images[].url` | `string` (uri) or `null` | Direct file URL; null when the platform withholds it, or when the link would only work from SocialTap's network or with a login. Often signed and expiring: see expires_at. |
| `images[].expires_at` | `string` (date-time) or `null` | When url stops working, RFC 3339 UTC, read from the platform's signed URL; null when unknown or when it does not expire. |
| `images[].thumbnail_url` | `string` (uri) or `null` | Poster or preview image URL. |
| `images[].width` | `integer` or `null` | Width in pixels. |
| `images[].height` | `integer` or `null` | Height in pixels. |
| `images[].duration_ms` | `integer` or `null` | Duration in milliseconds (video and audio only). |
| `images[].alt_text` | `string` or `null` | Accessibility text provided by the author or platform. |
| `account` | `object` or `null` | The platform account that represents the place (its business account or Page); null when none is linked. |
| `account.id` | `string` or `null` | Platform-native account ID; null when only the handle is known. |
| `account.username` | `string` or `null` | Handle without the @; null when the account has none. |
| `account.display_name` | `string` or `null` | Display name shown on the profile. |
| `account.url` | `string` (uri) or `null` | Canonical profile URL. |
| `account.avatar_url` | `string` (uri) or `null` | Profile picture URL. Platform CDN URLs can expire within hours. |
| `account.is_verified` | `boolean` or `null` | Platform verification badge; null where the platform has no badge. |
| `metrics` | `object` | Counts at fetch time; null = hidden or not exposed, 0 = zero. |
| `metrics.post_count` | `integer` or `null` | Public posts tagged with the place, as the platform counts them. |
| `metrics.review_count` | `integer` or `null` | Public reviews or recommendations of the place, as the platform counts them. |
| `metrics.image_count` | `integer` or `null` | Pictures the platform has of the place; more than the length of images when the source returns only the first ones. |
| `platform_specific` | `object` | Fields only this platform has, under its ID (platform_specific.\<platform>); each null when unknown. |
| `platform_specific.tiktok` | `object` or `null` | A TikTok POI's own fields. |
| `platform_specific.tiktok.category_path` | `string[]` | TikTok's category from broadest to most specific (Food and Drink, Fast Food, Pizza Fast Food), repeats dropped; category is the last. \[\] when TikTok shows none (listed in unknown_fields when the source cannot see it). |
| `platform_specific.tiktok.parent_id` | `string` or `null` | ID of the place TikTok files this one under (the city of a venue); a TikTok place ID. Null for a top-level place or when unknown. |
| `platform_specific.tiktok.parent_name` | `string` or `null` | Name of the place in parent_id. |
| `platform_specific.tiktok.rating` | `number` or `null` | Average TikTok review score out of 5 (metrics.review_count reviews behind it); null when the place is unrated. |
| `platform_specific.tiktok.is_claimed` | `boolean` or `null` | True when a business has claimed the place on TikTok, false when none has; null when unknown. |
| `platform_specific.tiktok.highlights` | `string[]` | The highlight tags TikTok shows from reviews (Excellent service, Pleasant atmosphere); \[\] when none (listed in unknown_fields when the source cannot see them). |
| `platform_specific.instagram` | `object` or `null` | An Instagram location's own fields. |
| `platform_specific.instagram.facebook_place_id` | `string` or `null` | ID of the Facebook place (Page) behind the location: the id of the same place on facebook. Null when none is linked or the source does not show it. |
| `platform_specific.facebook` | `object` or `null` | A Facebook place's own fields. |
| `platform_specific.facebook.checkin_count` | `integer` or `null` | People who checked in at the place, as Facebook shows it; null when Facebook shows no count (it shows none for a city). |
| `approximate_fields` | `string[]` | JSON paths of values rounded by the platform or parsed from display text (e.g. metrics.post_count). \[\] when all exact. |
| `unknown_fields` | `string[]` | JSON paths of lists whose \[\] means unknown rather than none (a source that cannot see them); null already means unknown for every other field. \[\] when every list is known. |

## Item errors

Besides the [request-level errors](https://socialtap.dev/docs/errors/index.md) every endpoint can return, place endpoints return:

| Code | HTTP | Retry | Meaning | What to do |
| --- | --- | --- | --- | --- |
| `not_found` | 404 | No | The item does not exist or was deleted. On GET /v1/requests/{id}/response: the response was not kept (details.reason says why). | Check the link or ID. Do not retry. |

---

[HTML version](https://socialtap.dev/resources/place/) · [Docs index for AI agents](https://socialtap.dev/llms.txt) · [All docs in one file](https://socialtap.dev/llms-full.txt)