# البحث عن أماكن على Threads الرابط الأساسي: https://sosoapi.ai/ar/docs/mcp/search-threads-locations `sosoapi_search_threads_locations` البحث باسم مكان مع أذونات الموقع؛ دون GPS. الوصول غير المعتمد يقتصر على Menlo Park. ## الملفات التعريفية ووسائل النقل الملفات التعريفية: full وسائل النقل: stdio, http اختر core أو full للأدوات التي يراها عميلك؛ لا يغيّر ذلك أذوناته. يحتاج رفع الملفات المحلية stdio ولا يتاح بـ HTTP. اضبط SOSOAPI_OUTPUT_SCHEMAS=1 لمخططات المخرجات بالاكتشاف. النتائج منظّمة بهذا الإعداد أوبدونه. ## الأذونات والآثار الجانبية تساعد الشروح العملاء على وصف الأداة. يظل كل استدعاء يفحص مصادقة المستخدم ودوره ووصوله إلى المورد وتفويض الإمكانات. ```json { "readOnlyHint": true, "destructiveHint": false, "idempotentHint": true, "openWorldHint": true } ``` `/analytics-api/threads-reads/location-search` — agent:operate; بيانات رسمية محدودة أو عدم توفر صريح؛ الأذونات الممنوحة لا تثبت اعتماد App Review للعامة ## حقول الإدخال ```json { "type": "object", "properties": { "workspace_id": { "type": "string", "format": "uuid" }, "social_account_id": { "type": "string", "format": "uuid" }, "query": { "type": "string", "minLength": 1, "maxLength": 200 } }, "required": [ "workspace_id", "social_account_id", "query" ], "additionalProperties": false } ``` ## مخرجات منظّمة يصف المخطط structuredContent في نتيجة أداة ناجحة. تشمل استجابة MCP أيضاً content وقد تضبط isError عند الفشل. للنشر، اقرأ النتيجة النهائية بدلاً من اعتبار القبول أوالنص تأكيداً. تشرح عملية API المرتبطة الأذونات وقواعد المحاولة. ```json { "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" }, "social_account_id": { "type": "string", "format": "uuid" }, "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" }, { "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" ], "additionalProperties": false }, "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" ], "additionalProperties": false } }, "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" ], "additionalProperties": false }, { "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" ], "additionalProperties": false } }, "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" ], "additionalProperties": false }, "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" } }, "additionalProperties": false }, "sources": { "maxItems": 2, "type": "array", "items": { "type": "string", "enum": [ "x-app-usage", "x-business-use-case-usage" ] } } }, "required": [ "provider", "usage", "sources" ], "additionalProperties": false } } }, "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" ], "$schema": "http://json-schema.org/draft-07/schema#", "additionalProperties": false } ``` ## مثال لاستدعاء أداة تستخدم الأمثلة قيماً خيالية مفحوصة بالمخططات. استبدل المعرّفات بالمفوّض لك، والوسائط بأصول جاهزة، والتواريخ بوقت نشر مؤكد. افحص أهلية الحساب قبل الكتابة. لا تُرسل الصفحة طلبات API. ```json { "name": "sosoapi_search_threads_locations", "arguments": { "workspace_id": "11111111-1111-4111-8111-111111111111", "social_account_id": "22222222-2222-4222-8222-222222222222", "query": "fictional market" } } ``` structuredContent ```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." ] } } ``` ## عمليات API الأساسية - [/analytics-api/threads-reads/location-search](https://sosoapi.ai/ar/docs/api/analytics-api-threads-reads-location-search)