Schemas

Place

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.

Schema

Single-item endpoints return this object as data; list endpoints return an array of them as data with a page object. The standard meta comes with every response.

platformstring

Platform ID (tiktok, instagram, …).

idstring

Platform-native place ID (TikTok POI ID, Instagram location ID, Facebook Page ID).

namestring

Place name as the platform shows it.

urlstring uri

Canonical place page URL.

typestring

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.

One ofvenueareaunknown

categorystringnullable

The platform's category label (Cafe, City, Pizza Fast Food), as shown; not normalized across platforms.

descriptionstringnullable

The place's description or about text; null when none is shown.

addressstringnullable

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.

citystringnullable

City or locality, as shown.

postal_codestringnullable

Postal or ZIP code.

country_codestringnullable

ISO 3166-1 alpha-2 country of the place.

latitudenumbernullable

WGS 84 latitude in degrees; null when the platform does not show coordinates (set together with longitude).

longitudenumbernullable

WGS 84 longitude in degrees; null when the platform does not show coordinates (set together with latitude).

phonestringnullable

The business's public phone number, as shown; null when none is shown.

website_urlstring urinullable

The place's own website.

price_rangeintegernullable

The business's price range, 1 (inexpensive, $) to 4 (expensive, $$$$); null when the platform shows none.

imagesobject[]

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.

Show 8 child fields

typestring

Kind of file. New values may be added; treat unknown values as other.

One ofimagevideoaudiogif

urlstring urinullable

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.

expires_atstring date-timenullable

When url stops working, RFC 3339 UTC, read from the platform's signed URL; null when unknown or when it does not expire.

thumbnail_urlstring urinullable

Poster or preview image URL.

widthintegernullable

Width in pixels.

heightintegernullable

Height in pixels.

duration_msintegernullable

Duration in milliseconds (video and audio only).

alt_textstringnullable

Accessibility text provided by the author or platform.

accountobjectnullable

The platform account that represents the place (its business account or Page); null when none is linked.

Show 6 child fields

idstringnullable

Platform-native account ID; null when only the handle is known.

usernamestringnullable

Handle without the @; null when the account has none.

display_namestringnullable

Display name shown on the profile.

urlstring urinullable

Canonical profile URL.

avatar_urlstring urinullable

Profile picture URL. Platform CDN URLs can expire within hours.

is_verifiedbooleannullable

Platform verification badge; null where the platform has no badge.

metricsobject

Counts at fetch time; null = hidden or not exposed, 0 = zero.

Show 3 child fields

post_countintegernullable

Public posts tagged with the place, as the platform counts them.

review_countintegernullable

Public reviews or recommendations of the place, as the platform counts them.

image_countintegernullable

Pictures the platform has of the place; more than the length of images when the source returns only the first ones.

platform_specificobject

Fields only this platform has, under its ID (platform_specific.<platform>); each null when unknown.

Show 3 child fields

tiktokobjectnullable

A TikTok POI's own fields.

Show 6 child fields

category_pathstring[]

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).

parent_idstringnullable

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.

parent_namestringnullable

Name of the place in parent_id.

ratingnumbernullable

Average TikTok review score out of 5 (metrics.review_count reviews behind it); null when the place is unrated.

is_claimedbooleannullable

True when a business has claimed the place on TikTok, false when none has; null when unknown.

highlightsstring[]

The highlight tags TikTok shows from reviews (Excellent service, Pleasant atmosphere); [] when none (listed in unknown_fields when the source cannot see them).

instagramobjectnullable

An Instagram location's own fields.

Show 1 child field

facebook_place_idstringnullable

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.

facebookobjectnullable

A Facebook place's own fields.

Show 1 child field

checkin_countintegernullable

People who checked in at the place, as Facebook shows it; null when Facebook shows no count (it shows none for a city).

approximate_fieldsstring[]

JSON paths of values rounded by the platform or parsed from display text (e.g. metrics.post_count). [] when all exact.

unknown_fieldsstring[]

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 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.

Example (Facebook Marketplace)

{
  "data": [
    {
      "account": null,
      "address": "Austin, IL",
      "approximate_fields": [
        "platform_specific.facebook.checkin_count"
      ],
      "category": null,
      "city": "Chicago",
      "country_code": null,
      "description": null,
      "id": "108120015875983",
      "images": [],
      "latitude": 41.894086,
      "longitude": -87.763202,
      "metrics": {
        "image_count": null,
        "post_count": null,
        "review_count": null
      },
      "name": "Austin",
      "phone": null,
      "platform": "facebook",
      "platform_specific": {
        "facebook": {
          "checkin_count": 25676
        }
      },
      "postal_code": "60644-1112",
      "price_range": null,
      "type": "area",
      "unknown_fields": [
        "images"
      ],
      "url": "https://www.facebook.com/marketplace/108120015875983/",
      "website_url": null
    },
    {
      "account": null,
      "address": "Austin, GA",
      "approximate_fields": [
        "platform_specific.facebook.checkin_count"
      ],
      "category": null,
      "city": "Marietta",
      "country_code": null,
      "description": null,
      "id": "312180006098697",
      "images": [],
      "latitude": 33.955058,
      "longitude": -84.529634,
      "metrics": {
        "image_count": null,
        "post_count": null,
        "review_count": null
      },
      "name": "Austin",
      "phone": null,
      "platform": "facebook",
      "platform_specific": {
        "facebook": {
          "checkin_count": 162
        }
      },
      "postal_code": "30060-1862",
      "price_range": null,
      "type": "area",
      "unknown_fields": [
        "images"
      ],
      "url": "https://www.facebook.com/marketplace/312180006098697/",
      "website_url": null
    },
    {
      "account": null,
      "address": null,
      "approximate_fields": [],
      "category": "City",
      "city": "Austin",
      "country_code": null,
      "description": null,
      "id": "106224666074625",
      "images": [],
      "latitude": 30.2677,
      "longitude": -97.7475,
      "metrics": {
        "image_count": null,
        "post_count": null,
        "review_count": null
      },
      "name": "Austin, Texas",
      "phone": null,
      "platform": "facebook",
      "platform_specific": {
        "facebook": {
          "checkin_count": null
        }
      },
      "postal_code": "78701",
      "price_range": null,
      "type": "area",
      "unknown_fields": [
        "images"
      ],
      "url": "https://www.facebook.com/marketplace/106224666074625/",
      "website_url": null
    }
  ],
  "page": {
    "has_more": false,
    "next_cursor": null,
    "next_cursor_expires_at": null,
    "end_reason": "platform_limit"
  },
  "meta": {
    "request_id": "req_3f9c2a7d1e8b4c6a9f0e2d4b6a8c0e1f",
    "platform": "facebook",
    "source": "api",
    "is_cached": false,
    "credits_charged": 1,
    "latency_ms": 297,
    "fetched_at": "2026-10-25T12:00:00Z",
    "input": null,
    "credits_remaining": 9999,
    "client_request_id": null,
    "warnings": []
  }
}

Long arrays and strings are shortened for display.