يُحمّل البحث عند استخدامه فقط. تصفّح جميع الفئات أدناه.

التحليلات والرؤى

البحث عن أماكن على Threads

البحث باسم مكان مع أذونات الموقع؛ دون GPS. الوصول غير المعتمد يقتصر على Menlo Park.

POST /analytics-api/threads-reads/location-search

مراجعة العقد: · sha256:11debf801a5e6096

نظرة عامة

البحث باسم مكان مع أذونات الموقع؛ دون GPS. الوصول غير المعتمد يقتصر على Menlo Park.

قد يعني نجاح HTTP قبول الطلب لا اكتماله. للعمل الخلفي، احفظ المعرّف المُعاد وتابع العملية نفسها حتى تنتهي. لا يُعدّ المنشور المجدول أوالمقبول منشوراً حتى تأكيد المنصة؛ انتهاء مهلة العميل لا يثبت النتيجة.

المصادقة والأذونات

فئات بيانات الاعتماد المقبولة
user_session, delegated_oauth, personal_access_token
إمكانية مفوّضة
agent:operate
الحد الأدنى لدور مساحة العمل
viewer
نطاق الوصول
الموارد التي يحق لهذا المستخدم الوصول إليها
تلزم موافقة تشمل جميع مساحات العمل
لا
يغيّر الحالة
لا
متى تُعدّ العملية مكتملة
bounded official data or explicit unavailable; granted scopes do not establish public App Review approval

لا يستخدم الرمز إلا حقوق مالكه. يفحص كل طلب عضوية مساحة العمل وملكية المورد والمساحات المحددة والإمكانات الممنوحة. يغيّر core و full الأدوات المعروضة؛ ولا يمنحان وصولاً.

حقول الطلب

تعني «مطلوب» داخل الكائن الأب والفرع المختار. الحقل الابن المطلوب لا يجعل الأب الاختياري مطلوباً. نُسخت القواعد وأسماء الحقول أدناه من العقد.

حقول الطلب
الحقل / الفرعالنوع / مطلوبالقيود
$objectمطلوب في العنصر الأب
  • additionalProperties: false
workspace_idstringمطلوب في العنصر الأب
  • format: "uuid"
  • pattern: "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
social_account_idstringمطلوب في العنصر الأب
  • format: "uuid"
  • pattern: "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
querystringمطلوب في العنصر الأب
  • minLength: 1
  • maxLength: 200
مخطط JSON Schema الكامل
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "workspace_id": {
      "type": "string",
      "format": "uuid",
      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
    },
    "social_account_id": {
      "type": "string",
      "format": "uuid",
      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
    },
    "query": {
      "type": "string",
      "minLength": 1,
      "maxLength": 200
    }
  },
  "required": [
    "workspace_id",
    "social_account_id",
    "query"
  ],
  "additionalProperties": false
}

الاستجابة والاكتمال

رموز نجاح HTTP: 200. عندما تكتمل العملية: bounded official data or explicit unavailable; granted scopes do not establish public App Review approval.

قد يعني نجاح HTTP قبول الطلب لا اكتماله. للعمل الخلفي، احفظ المعرّف المُعاد وتابع العملية نفسها حتى تنتهي. لا يُعدّ المنشور المجدول أوالمقبول منشوراً حتى تأكيد المنصة؛ انتهاء مهلة العميل لا يثبت النتيجة.

تعني «مطلوب» داخل الكائن الأب والفرع المختار. الحقل الابن المطلوب لا يجعل الأب الاختياري مطلوباً. نُسخت القواعد وأسماء الحقول أدناه من العقد.

الاستجابة والاكتمال
الحقل / الفرعالنوع / مطلوبالقيود
$objectمطلوب في العنصر الأب—
contract_versionstringمطلوب في العنصر الأب
  • const: "threads-reads/v1"
operationstringمطلوب في العنصر الأب
  • const: "location_search"
sourcestringمطلوب في العنصر الأب
  • const: "official_threads_api"
workspace_idstringمطلوب في العنصر الأب
  • format: "uuid"
  • pattern: "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
social_account_idstringمطلوب في العنصر الأب
  • format: "uuid"
  • pattern: "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
provider_account_idstringمطلوب في العنصر الأب
  • pattern: "^\\d{2,20}$"
provider_app_identitystring | nullمطلوب في العنصر الأب—
provider_app_identityanyOf 1stringمطلوب في العنصر الأب
  • minLength: 1
  • maxLength: 100
provider_app_identityanyOf 2nullمطلوب في العنصر الأب—
oauth_snapshot_idstring | nullمطلوب في العنصر الأب—
oauth_snapshot_idanyOf 1stringمطلوب في العنصر الأب
  • format: "uuid"
  • pattern: "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
oauth_snapshot_idanyOf 2nullمطلوب في العنصر الأب—
fetched_atstringمطلوب في العنصر الأب
  • format: "date-time"
  • pattern: "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"
statusstringمطلوب في العنصر الأب
  • enum: ["available","partial","unavailable"]
unavailable_reasonstring | nullمطلوب في العنصر الأب—
unavailable_reasonanyOf 1stringمطلوب في العنصر الأب
  • enum: ["grant_inventory_unknown","missing_permissions","issuing_app_unknown","credential_unavailable","credential_expired","account_unhealthy","provider_denied","provider_rate_limited","provider_unavailable","provider_response_invalid"]
unavailable_reasonanyOf 2nullمطلوب في العنصر الأب—
accessobjectمطلوب في العنصر الأب—
access.required_permissionsarrayمطلوب في العنصر الأب
  • maxItems: 4
access.required_permissions[]stringاختياري / عنصر
  • pattern: "^[a-z][a-z0-9_]{0,99}$"
access.missing_permissionsarrayمطلوب في العنصر الأب
  • maxItems: 4
access.missing_permissions[]stringاختياري / عنصر
  • pattern: "^[a-z][a-z0-9_]{0,99}$"
access.permission_statestringمطلوب في العنصر الأب
  • enum: ["granted","missing","unknown"]
access.grant_evidencestringمطلوب في العنصر الأب
  • enum: ["exact","unknown"]
access.app_accessstringمطلوب في العنصر الأب
  • const: "unverified"
dataarrayمطلوب في العنصر الأب
  • maxItems: 100
data[]objectاختياري / عنصر—
data[].idstringمطلوب في العنصر الأب
  • pattern: "^\\d{2,20}$"
data[].textstring | nullمطلوب في العنصر الأب—
data[].textanyOf 1stringمطلوب في العنصر الأب
  • maxLength: 30000
data[].textanyOf 2nullمطلوب في العنصر الأب—
data[].usernamestring | nullمطلوب في العنصر الأب—
data[].usernameanyOf 1stringمطلوب في العنصر الأب
  • pattern: "^[A-Za-z0-9._]{1,30}$"
data[].usernameanyOf 2nullمطلوب في العنصر الأب—
data[].permalinkstring | nullمطلوب في العنصر الأب—
data[].permalinkanyOf 1stringمطلوب في العنصر الأب
  • format: "uri"
data[].permalinkanyOf 2nullمطلوب في العنصر الأب—
data[].timestampstring | nullمطلوب في العنصر الأب—
data[].timestampanyOf 1stringمطلوب في العنصر الأب
  • format: "date-time"
  • pattern: "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"
data[].timestampanyOf 2nullمطلوب في العنصر الأب—
data[].media_typestring | nullمطلوب في العنصر الأب—
data[].media_typeanyOf 1stringمطلوب في العنصر الأب
  • enum: ["TEXT","TEXT_POST","IMAGE","VIDEO","CAROUSEL_ALBUM","AUDIO","REPOST_FACADE"]
data[].media_typeanyOf 2nullمطلوب في العنصر الأب—
data[].is_replyboolean | nullمطلوب في العنصر الأب—
data[].is_quote_postboolean | nullمطلوب في العنصر الأب—
data[].has_repliesboolean | nullمطلوب في العنصر الأب—
data[].root_post_idstring | nullاختياري / عنصر—
data[].root_post_idanyOf 1stringاختياري / عنصر
  • pattern: "^\\d{2,20}$"
data[].root_post_idanyOf 2nullاختياري / عنصر—
data[].replied_to_idstring | nullاختياري / عنصر—
data[].replied_to_idanyOf 1stringاختياري / عنصر
  • pattern: "^\\d{2,20}$"
data[].replied_to_idanyOf 2nullاختياري / عنصر—
profileobject | nullمطلوب في العنصر الأب—
profileanyOf 1objectمطلوب في العنصر الأب—
profile.usernameanyOf 1stringمطلوب في العنصر الأب
  • pattern: "^[A-Za-z0-9._]{1,30}$"
profile.nameanyOf 1string | nullمطلوب في العنصر الأب—
profile.nameanyOf 1 / anyOf 1stringمطلوب في العنصر الأب
  • maxLength: 200
profile.nameanyOf 1 / anyOf 2nullمطلوب في العنصر الأب—
profile.biographyanyOf 1string | nullمطلوب في العنصر الأب—
profile.biographyanyOf 1 / anyOf 1stringمطلوب في العنصر الأب
  • maxLength: 2000
profile.biographyanyOf 1 / anyOf 2nullمطلوب في العنصر الأب—
profile.is_verifiedanyOf 1boolean | nullمطلوب في العنصر الأب—
profile.follower_countanyOf 1integer | nullمطلوب في العنصر الأب—
profile.follower_countanyOf 1 / anyOf 1integerمطلوب في العنصر الأب
  • minimum: 0
  • maximum: 9007199254740991
profile.follower_countanyOf 1 / anyOf 2nullمطلوب في العنصر الأب—
profileanyOf 2nullمطلوب في العنصر الأب—
locationsarrayمطلوب في العنصر الأب
  • maxItems: 100
locations[]objectاختياري / عنصر—
locations[].idstringمطلوب في العنصر الأب
  • pattern: "^\\d{2,20}$"
locations[].namestring | nullمطلوب في العنصر الأب—
locations[].nameanyOf 1stringمطلوب في العنصر الأب
  • maxLength: 200
locations[].nameanyOf 2nullمطلوب في العنصر الأب—
locations[].addressstring | nullمطلوب في العنصر الأب—
locations[].addressanyOf 1stringمطلوب في العنصر الأب
  • maxLength: 500
locations[].addressanyOf 2nullمطلوب في العنصر الأب—
locations[].citystring | nullمطلوب في العنصر الأب—
locations[].cityanyOf 1stringمطلوب في العنصر الأب
  • maxLength: 200
locations[].cityanyOf 2nullمطلوب في العنصر الأب—
locations[].countrystring | nullمطلوب في العنصر الأب—
locations[].countryanyOf 1stringمطلوب في العنصر الأب
  • maxLength: 200
locations[].countryanyOf 2nullمطلوب في العنصر الأب—
locations[].postal_codestring | nullمطلوب في العنصر الأب—
locations[].postal_codeanyOf 1stringمطلوب في العنصر الأب
  • maxLength: 100
locations[].postal_codeanyOf 2nullمطلوب في العنصر الأب—
root_post_idstringاختياري / عنصر
  • pattern: "^\\d{2,20}$"
target_usernamestringاختياري / عنصر
  • pattern: "^[A-Za-z0-9._]{1,30}$"
coverageobjectمطلوب في العنصر الأب—
coverage.completebooleanمطلوب في العنصر الأب
  • const: false
coverage.next_cursorstring | nullمطلوب في العنصر الأب—
coverage.next_cursoranyOf 1stringمطلوب في العنصر الأب
  • minLength: 1
  • maxLength: 4096
coverage.next_cursoranyOf 2nullمطلوب في العنصر الأب—
coverage.omitted_rowsintegerمطلوب في العنصر الأب
  • minimum: 0
  • maximum: 9007199254740991
coverage.reasonsarrayمطلوب في العنصر الأب
  • maxItems: 8
coverage.reasons[]stringاختياري / عنصر
  • maxLength: 400
quotaarrayمطلوب في العنصر الأب
  • maxItems: 1
quota[]objectاختياري / عنصر—
quota[].providerstringمطلوب في العنصر الأب
  • const: "meta"
quota[].usageobjectمطلوب في العنصر الأب—
quota[].usage.call_countnumberاختياري / عنصر—
quota[].usage.total_cputimenumberاختياري / عنصر—
quota[].usage.total_timenumberاختياري / عنصر—
quota[].usage.estimated_time_to_regain_accessnumberاختياري / عنصر—
quota[].sourcesarrayمطلوب في العنصر الأب
  • maxItems: 2
quota[].sources[]stringاختياري / عنصر
  • enum: ["x-app-usage","x-business-use-case-usage"]
مخطط JSON Schema الكامل
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "contract_version": {
      "type": "string",
      "const": "threads-reads/v1"
    },
    "operation": {
      "type": "string",
      "const": "location_search"
    },
    "source": {
      "type": "string",
      "const": "official_threads_api"
    },
    "workspace_id": {
      "type": "string",
      "format": "uuid",
      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
    },
    "social_account_id": {
      "type": "string",
      "format": "uuid",
      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
    },
    "provider_account_id": {
      "type": "string",
      "pattern": "^\\d{2,20}$"
    },
    "provider_app_identity": {
      "anyOf": [
        {
          "type": "string",
          "minLength": 1,
          "maxLength": 100
        },
        {
          "type": "null"
        }
      ]
    },
    "oauth_snapshot_id": {
      "anyOf": [
        {
          "type": "string",
          "format": "uuid",
          "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
        },
        {
          "type": "null"
        }
      ]
    },
    "fetched_at": {
      "type": "string",
      "format": "date-time",
      "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"
    },
    "status": {
      "type": "string",
      "enum": [
        "available",
        "partial",
        "unavailable"
      ]
    },
    "unavailable_reason": {
      "anyOf": [
        {
          "type": "string",
          "enum": [
            "grant_inventory_unknown",
            "missing_permissions",
            "issuing_app_unknown",
            "credential_unavailable",
            "credential_expired",
            "account_unhealthy",
            "provider_denied",
            "provider_rate_limited",
            "provider_unavailable",
            "provider_response_invalid"
          ]
        },
        {
          "type": "null"
        }
      ]
    },
    "access": {
      "type": "object",
      "properties": {
        "required_permissions": {
          "maxItems": 4,
          "type": "array",
          "items": {
            "type": "string",
            "pattern": "^[a-z][a-z0-9_]{0,99}$"
          }
        },
        "missing_permissions": {
          "maxItems": 4,
          "type": "array",
          "items": {
            "type": "string",
            "pattern": "^[a-z][a-z0-9_]{0,99}$"
          }
        },
        "permission_state": {
          "type": "string",
          "enum": [
            "granted",
            "missing",
            "unknown"
          ]
        },
        "grant_evidence": {
          "type": "string",
          "enum": [
            "exact",
            "unknown"
          ]
        },
        "app_access": {
          "type": "string",
          "const": "unverified"
        }
      },
      "required": [
        "required_permissions",
        "missing_permissions",
        "permission_state",
        "grant_evidence",
        "app_access"
      ]
    },
    "data": {
      "maxItems": 100,
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "pattern": "^\\d{2,20}$"
          },
          "text": {
            "anyOf": [
              {
                "type": "string",
                "maxLength": 30000
              },
              {
                "type": "null"
              }
            ]
          },
          "username": {
            "anyOf": [
              {
                "type": "string",
                "pattern": "^[A-Za-z0-9._]{1,30}$"
              },
              {
                "type": "null"
              }
            ]
          },
          "permalink": {
            "anyOf": [
              {
                "type": "string",
                "format": "uri"
              },
              {
                "type": "null"
              }
            ]
          },
          "timestamp": {
            "anyOf": [
              {
                "type": "string",
                "format": "date-time",
                "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"
              },
              {
                "type": "null"
              }
            ]
          },
          "media_type": {
            "anyOf": [
              {
                "type": "string",
                "enum": [
                  "TEXT",
                  "TEXT_POST",
                  "IMAGE",
                  "VIDEO",
                  "CAROUSEL_ALBUM",
                  "AUDIO",
                  "REPOST_FACADE"
                ]
              },
              {
                "type": "null"
              }
            ]
          },
          "is_reply": {
            "type": [
              "boolean",
              "null"
            ]
          },
          "is_quote_post": {
            "type": [
              "boolean",
              "null"
            ]
          },
          "has_replies": {
            "type": [
              "boolean",
              "null"
            ]
          },
          "root_post_id": {
            "anyOf": [
              {
                "type": "string",
                "pattern": "^\\d{2,20}$"
              },
              {
                "type": "null"
              }
            ]
          },
          "replied_to_id": {
            "anyOf": [
              {
                "type": "string",
                "pattern": "^\\d{2,20}$"
              },
              {
                "type": "null"
              }
            ]
          }
        },
        "required": [
          "id",
          "text",
          "username",
          "permalink",
          "timestamp",
          "media_type",
          "is_reply",
          "is_quote_post",
          "has_replies"
        ]
      }
    },
    "profile": {
      "anyOf": [
        {
          "type": "object",
          "properties": {
            "username": {
              "type": "string",
              "pattern": "^[A-Za-z0-9._]{1,30}$"
            },
            "name": {
              "anyOf": [
                {
                  "type": "string",
                  "maxLength": 200
                },
                {
                  "type": "null"
                }
              ]
            },
            "biography": {
              "anyOf": [
                {
                  "type": "string",
                  "maxLength": 2000
                },
                {
                  "type": "null"
                }
              ]
            },
            "is_verified": {
              "type": [
                "boolean",
                "null"
              ]
            },
            "follower_count": {
              "anyOf": [
                {
                  "type": "integer",
                  "minimum": 0,
                  "maximum": 9007199254740991
                },
                {
                  "type": "null"
                }
              ]
            }
          },
          "required": [
            "username",
            "name",
            "biography",
            "is_verified",
            "follower_count"
          ]
        },
        {
          "type": "null"
        }
      ]
    },
    "locations": {
      "maxItems": 100,
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "pattern": "^\\d{2,20}$"
          },
          "name": {
            "anyOf": [
              {
                "type": "string",
                "maxLength": 200
              },
              {
                "type": "null"
              }
            ]
          },
          "address": {
            "anyOf": [
              {
                "type": "string",
                "maxLength": 500
              },
              {
                "type": "null"
              }
            ]
          },
          "city": {
            "anyOf": [
              {
                "type": "string",
                "maxLength": 200
              },
              {
                "type": "null"
              }
            ]
          },
          "country": {
            "anyOf": [
              {
                "type": "string",
                "maxLength": 200
              },
              {
                "type": "null"
              }
            ]
          },
          "postal_code": {
            "anyOf": [
              {
                "type": "string",
                "maxLength": 100
              },
              {
                "type": "null"
              }
            ]
          }
        },
        "required": [
          "id",
          "name",
          "address",
          "city",
          "country",
          "postal_code"
        ]
      }
    },
    "root_post_id": {
      "type": "string",
      "pattern": "^\\d{2,20}$"
    },
    "target_username": {
      "type": "string",
      "pattern": "^[A-Za-z0-9._]{1,30}$"
    },
    "coverage": {
      "type": "object",
      "properties": {
        "complete": {
          "type": "boolean",
          "const": false
        },
        "next_cursor": {
          "anyOf": [
            {
              "type": "string",
              "minLength": 1,
              "maxLength": 4096
            },
            {
              "type": "null"
            }
          ]
        },
        "omitted_rows": {
          "type": "integer",
          "minimum": 0,
          "maximum": 9007199254740991
        },
        "reasons": {
          "maxItems": 8,
          "type": "array",
          "items": {
            "type": "string",
            "maxLength": 400
          }
        }
      },
      "required": [
        "complete",
        "next_cursor",
        "omitted_rows",
        "reasons"
      ]
    },
    "quota": {
      "maxItems": 1,
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "provider": {
            "type": "string",
            "const": "meta"
          },
          "usage": {
            "type": "object",
            "properties": {
              "call_count": {
                "type": "number"
              },
              "total_cputime": {
                "type": "number"
              },
              "total_time": {
                "type": "number"
              },
              "estimated_time_to_regain_access": {
                "type": "number"
              }
            }
          },
          "sources": {
            "maxItems": 2,
            "type": "array",
            "items": {
              "type": "string",
              "enum": [
                "x-app-usage",
                "x-business-use-case-usage"
              ]
            }
          }
        },
        "required": [
          "provider",
          "usage",
          "sources"
        ]
      }
    }
  },
  "required": [
    "contract_version",
    "operation",
    "source",
    "workspace_id",
    "social_account_id",
    "provider_account_id",
    "provider_app_identity",
    "oauth_snapshot_id",
    "fetched_at",
    "status",
    "unavailable_reason",
    "access",
    "data",
    "profile",
    "locations",
    "coverage",
    "quota"
  ]
}

الأخطاء وإعادة المحاولة بأمان

افحص حالة HTTP والجسم. قد يحوي خطأ التحقق 400 ‏ZodError؛ تستخدم أخطاء المعالج error و message و code. احتفظ بـ request_id أو x-request-id للتشخيص دون اعتماد. أصلح أخطاء وصول 401/403 قبل المحاولة واتّبع Retry-After لـ 429. لكتابة غير مؤكدة أو 5xx، اقرأ الموجود أولاً. أعِد مفتاح منع التكرار حيث يُدعم فقط؛ تختلف المحاولة حسب العملية ولا تضمن التسليم مرة واحدة بالضبط.

دليل استكشاف الأخطاء وإصلاحها

أمثلة

تستخدم الأمثلة قيماً خيالية مفحوصة بالمخططات. استبدل المعرّفات بالمفوّض لك، والوسائط بأصول جاهزة، والتواريخ بوقت نشر مؤكد. افحص أهلية الحساب قبل الكتابة. لا تُرسل الصفحة طلبات API.

اضبط SOSOAPI_ACCESS_TOKEN على خادمك ببيانات اعتماد تقبلها العملية، وأبقِه خارج شيفرة المتصفح. لوكيل الذكاء الاصطناعي، استخدم sosoapi auth login للدخول بالمتصفح ودع CLI يحدّث بيانات اعتماده.

request.json

{
  "workspace_id": "11111111-1111-4111-8111-111111111111",
  "social_account_id": "22222222-2222-4222-8222-222222222222",
  "query": "fictional market"
}

cURL

curl --request POST \
  "https://gqeshlawtcexsapabaui.supabase.co/functions/v1/analytics-api/threads-reads/location-search" \
  -H "Authorization: Bearer $SOSOAPI_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  --data-binary @request.json

JavaScript

// Server-side JavaScript. Do not print tokens or credential-bearing responses.
const token = process.env.SOSOAPI_ACCESS_TOKEN;
if (!token) throw new Error("Set an accepted credential for this operation");
const response = await fetch("https://gqeshlawtcexsapabaui.supabase.co/functions/v1/analytics-api/threads-reads/location-search", {
  method: "POST",
  headers: { "Content-Type": "application/json", Authorization: "Bearer " + token },
  body: JSON.stringify({
  "workspace_id": "11111111-1111-4111-8111-111111111111",
  "social_account_id": "22222222-2222-4222-8222-222222222222",
  "query": "fictional market"
})
});
const result = await response.json();
// Check response.ok, the operation-specific body and completion state before continuing.

CLI

npx sosoapi api post /analytics-api/threads-reads/location-search < request.json

مثال استجابة اصطناعية

{
  "workspace_id": "11111111-1111-4111-8111-111111111111",
  "social_account_id": "22222222-2222-4222-8222-222222222222",
  "contract_version": "threads-reads/v1",
  "operation": "location_search",
  "source": "official_threads_api",
  "provider_account_id": "12345",
  "provider_app_identity": null,
  "oauth_snapshot_id": null,
  "fetched_at": "2099-01-15T09:00:00Z",
  "status": "unavailable",
  "unavailable_reason": "issuing_app_unknown",
  "access": {
    "required_permissions": [
      "threads_basic",
      "threads_location_tagging"
    ],
    "missing_permissions": [],
    "permission_state": "unknown",
    "grant_evidence": "unknown",
    "app_access": "unverified"
  },
  "data": [],
  "profile": null,
  "locations": [],
  "quota": [],
  "coverage": {
    "complete": false,
    "next_cursor": null,
    "omitted_rows": 0,
    "reasons": [
      "Fictional documentation example: no provider request was made and no account data was read.",
      "App access and any pending permission review remain unverified; this is not successful provider or public-access evidence."
    ]
  }
}

MCP: sosoapi_search_threads_locations