GET/api/v4/listings/scans/{scanId}

الحصول على listings scan

يعيد listings scan واحدًا مع ملخصه ونتائجه لكل دليل، وتكون هذه البيانات جزئية ما دام الفحص قيد التشغيل.

يتطلب مفتاح API. راجع المصادقة لمعرفة تنسيق الترويسة وتدوير المفاتيح.

المعلمات

المسار

الاسم	النوع	مطلوب	الوصف
scanId	string	مطلوب	The scan `id` returned by POST /listings/scans or listed by GET /listings/scans.

الاستجابات

200A completed scan. The real response lists every directory in `results`, usually around 60. This example is trimmed to six entries, one of each kind described below.

Response

{  "data": {    "listingScan": {      "id": "TGlzdGluZ1NjYW46Mzk0YTRhNWMtZjcwMy00NjZiLTg2NjAtMDU4MTlmNDhkZjMz",      "status": "COMPLETED",      "source": "DIRECTORY_SEARCH",      "locationId": null,      "resultsAsOf": "2026-11-05T07:01:51Z",      "createdAt": "2026-11-05T07:01:08Z",      "startedAt": "2026-11-05T07:01:11Z",      "completedAt": "2026-11-05T07:01:51Z",      "business": {        "name": "Joe's Pizza",        "street": "7 Carmine Street",        "city": "New York",        "stateIso": "NY",        "postalCode": "10014",        "countryIso": "US",        "phone": "+12123661182"      },      "summary": {        "total": 62,        "found": 21,        "accurate": 18,        "inaccurate": 2,        "notFound": 41,        "pending": 0,        "unavailable": 0      },      "failure": null,      "results": [        {          "directory": {            "id": 1,            "name": "Google Maps",            "url": "maps.google.com"          },          "status": "FOUND",          "accurate": true,          "accuracySource": "DIRECTORY_MATCH",          "accuracy": {            "name": {              "status": "ACCURATE",              "message": null            },            "address": {              "status": "ACCURATE",              "message": null            },            "phone": {              "status": "ACCURATE",              "message": null            }          },          "listing": {            "name": "Joe's Pizza",            "street": "7 Carmine Street",            "city": "New York",            "state": "NY",            "postalCode": "10014",            "country": "US",            "fullAddress": "7 Carmine St, New York, NY 10014, USA",            "phones": [              "+1 212-366-1182"            ],            "url": "https://maps.google.com/?cid=4877966330195296067"          },          "syncStatus": null        },        {          "directory": {            "id": 2,            "name": "Yelp",            "url": "yelp.com"          },          "status": "FOUND",          "accurate": true,          "accuracySource": "DIRECTORY_MATCH",          "accuracy": {            "name": {              "status": "ACCURATE",              "message": null            },            "address": {              "status": "ACCURATE",              "message": null            },            "phone": {              "status": "ACCURATE",              "message": null            }          },          "listing": {            "name": "Joe's Pizza",            "street": "7 Carmine St",            "city": "New York",            "state": "NY",            "postalCode": "10014",            "country": "US",            "fullAddress": "7 Carmine St, New York, NY 10014",            "phones": [              "+12123661182"            ],            "url": "https://www.yelp.com/biz/joes-pizza-new-york-4"          },          "syncStatus": null        },        {          "directory": {            "id": 374,            "name": "Map Quest",            "url": "www.mapquest.com"          },          "status": "FOUND",          "accurate": null,          "accuracySource": "DIRECTORY_MATCH",          "accuracy": {            "name": {              "status": "ACCURATE",              "message": null            },            "address": {              "status": "MISSING",              "message": "Not shown"            },            "phone": {              "status": "MISSING",              "message": "Not shown"            }          },          "listing": {            "name": "Joe's Pizza",            "street": "7 Carmine St",            "city": "New York",            "state": "NY",            "postalCode": "10014",            "country": null,            "fullAddress": "7 Carmine St, New York, NY 10014, US",            "phones": [],            "url": null          },          "syncStatus": null        },        {          "directory": {            "id": 352,            "name": "YellowPages",            "url": "www.yellowpages.com"          },          "status": "NOT_FOUND",          "accurate": null,          "accuracySource": "DIRECTORY_MATCH",          "accuracy": null,          "listing": null,          "syncStatus": null        },        {          "directory": {            "id": 50,            "name": "Judys Book",            "url": "judysbook.com"          },          "status": "FOUND",          "accurate": false,          "accuracySource": "DIRECTORY_MATCH",          "accuracy": {            "name": {              "status": "ACCURATE",              "message": null            },            "address": {              "status": "ACCURATE",              "message": null            },            "phone": {              "status": "INACCURATE",              "message": "Phone number does not match"            }          },          "listing": {            "name": "Joe's Pizza",            "street": "7 CARMINE ST",            "city": "New York",            "state": "NY",            "postalCode": "10014",            "country": null,            "fullAddress": "7 CARMINE ST, New York, NY 10014",            "phones": [              "8553685707"            ],            "url": "https://www.judysbook.com/Joes-Pizza-Uncategorized-newyork-r29271293.htm"          },          "syncStatus": null        },        {          "directory": {            "id": 350,            "name": "Uber",            "url": "uber.com"          },          "status": "FOUND",          "accurate": true,          "accuracySource": "DIRECTORY_MATCH",          "accuracy": {            "name": {              "status": "ACCURATE",              "message": null            },            "address": {              "status": "ACCURATE",              "message": null            },            "phone": {              "status": "ACCURATE",              "message": null            }          },          "listing": {            "name": "Joe's Pizza",            "street": "7 Carmine Street",            "city": "New York",            "state": "NY",            "postalCode": "10014",            "country": "US",            "fullAddress": "7 Carmine St, New York, NY 10014, USA",            "phones": [              "+1 212-366-1182"            ],            "url": null          },          "syncStatus": null        }      ]    }  }}

200A failed scan. `failure` has the code and message, and `results` is empty.

Response

{  "data": {    "listingScan": {      "id": "TGlzdGluZ1NjYW46ZGVkZTNhOTgtNDA5Ni00ZDI3LWJlMjUtMzY3YTYxOTk4Y2Y1",      "status": "FAILED",      "source": "DIRECTORY_SEARCH",      "locationId": null,      "resultsAsOf": null,      "createdAt": "2026-11-03T08:53:18Z",      "startedAt": null,      "completedAt": "2026-11-03T08:53:18Z",      "business": {        "name": "Franklin Barbecue",        "street": "900 E 11th St",        "city": "Austin",        "stateIso": "TX",        "postalCode": "78702",        "countryIso": "US",        "phone": "+15126531187"      },      "summary": {        "total": 0,        "found": 0,        "accurate": 0,        "inaccurate": 0,        "notFound": 0,        "pending": 0,        "unavailable": 0      },      "failure": {        "code": "SY83010",        "message": "SY83010: Listing scans are temporarily unavailable, try again later",        "field": null      },      "results": []    }  }}

401Unauthenticated, missing or invalid API key.

404No scan with that ID on this account, or the scan is older than 90 days (`SY83005`).

Response

{  "data": {    "listingScan": null  },  "errors": [    {      "message": "SY83005: Listing scan not found"    }  ]}

429Rate limit exceeded. Retry after the `Retry-After` header value.

يُرجع فحصًا واحدًا أُنشئ بواسطة POST /listings/scans، مع summary الخاص به وسجل results[] لكل دليل. أثناء تشغيل الفحص، يحتوي results على ما تم التحقق منه حتى الآن، وقد تظل بعض السجلات في حالة PENDING. عندما تكون قيمة status هي COMPLETED، تكون النتائج نهائية.

حالة الاستخدام: قراءة التقرير بعد وصول إشعار webhook. يتضمن الحدث listing_scan.completed الفحص كاملًا بالفعل، لذا لا تحتاج معظم عمليات التكامل إلى أي طلب قراءة. استخدم نقطة النهاية هذه لإعادة قراءة فحص لاحقًا، أو لعرضه في لوحة التحكم، أو لاسترداده إذا فاتك إشعار webhook.

حالة الاستخدام: الاستقصاء الدوري عندما لا تتوفر إشعارات webhook. اقرأ الفحص كل 15 ثانية حتى تكون قيمة status هي COMPLETED أو FAILED. لا تستقصِ بوتيرة أسرع: يُحتسب كل طلب قراءة ضمن حد معدل الطلبات. يُحتفظ بالفحوص لمدة 90 يومًا؛ بعد ذلك، تُرجع نقطة النهاية هذه 404 مع SY83005.

حالات الفحص

`status`	نهائية	المعنى
`QUEUED`	لا	تم قبول الفحص، لكنه لم يبدأ. `results` فارغ.
`IN_PROGRESS`	لا	جارٍ التحقق من الأدلة. يُملأ `results` تدريجيًا أثناء التحقق.
`COMPLETED`	نعم	تم التحقق من كل دليل. النتائج نهائية.
`FAILED`	نعم	تعذّر تشغيل الفحص. اقرأ `failure`. لم يُحتسب من حصتك.

كائن الفحص

الحقل	النوع	الوصف
`id`	string	معرّف الفحص. استخدمه مع نقطة النهاية هذه.
`status`	string	`QUEUED` أو `IN_PROGRESS` أو `COMPLETED` أو `FAILED`.
`source`	string	مصدر النتائج: `DIRECTORY_SEARCH` (بحث جديد)، أو `RECENT_SCAN` (نسخة من فحص لنشاط تجاري مطابق أجراه أي مستخدم خلال آخر 7 أيام)، أو `LOCATION_LISTINGS` (طابق النشاط التجاري أحد مواقعك).
`locationId`	string أو null	الموقع المطابق. تُعيَّن قيمته فقط عندما تكون قيمة `source` هي `LOCATION_LISTINGS`.
`resultsAsOf`	string أو null	وقت جمع بيانات الأدلة. في حالة نسخة `RECENT_SCAN`، يسبق هذا الوقت `createdAt`. تكون القيمة `null` إلى أن تتوفر نتائج.
`createdAt`	string	وقت إنشاء الفحص.
`startedAt`	string أو null	وقت بدء التحقق من الأدلة.
`completedAt`	string أو null	وقت وصول الفحص إلى حالة `COMPLETED` أو `FAILED`.
`business`	object	النشاط التجاري الذي تم فحصه: `name` و`street` و`city` و`stateIso` و`postalCode` و`countryIso` و`phone`. يُرجع رقم الهاتف بالصيغة الدولية.
`summary`	object	الأعداد الإجمالية عبر النتائج: `total` و`found` و`accurate` و`inaccurate` و`notFound` و`pending` و`unavailable`.
`failure`	object أو null	تُعيَّن قيمته عندما تكون قيمة `status` هي `FAILED`: `code` و`message`، وكذلك `field` إذا كان السبب حقل إدخال واحدًا.
`results`	array	سجل واحد لكل دليل. تكون المصفوفة فارغة عند فشل الفحص.

يحصي summary.found الأدلة التي تتضمن إدراجًا للنشاط التجاري. ومن بين هذه الأدلة، يحصي accurate الأدلة التي تتطابق فيها التفاصيل، ويحصي inaccurate الأدلة التي لا تتطابق فيها التفاصيل. يُحتسب إدراج النشاط التجاري الذي عُثر عليه وتم تأكيد وجوده دون التحقق من كل حقل على حدة ضمن found فقط، ولذلك قد يكون مجموع accurate وinaccurate أقل من found.

نتيجة

الحقل	النوع	الوصف
`directory`	object	الدليل: `id` و`name` و`url`. يطابق `id` معرّف الموقع الإلكتروني المستخدم في مواضع أخرى من واجهة API.
`status`	string	`FOUND` أو `NOT_FOUND` أو `UNAVAILABLE` أو `PENDING`.
`accurate`	boolean أو null	ما إذا كان إدراج النشاط التجاري يطابق النشاط التجاري. انظر أدناه.
`accuracySource`	string	كيفية تحديد الدقة: `DIRECTORY_MATCH` (تمت مقارنة إدراج النشاط التجاري بالنشاط التجاري) أو `SYNC_STATUS` (استُمدت من حالة مزامنة موقعك).
`accuracy`	object أو null	نتيجة التحقق لكل حقل: `name` و`address` و`phone`، كل منها `{ status, message }`. تكون القيمة `null` عند عدم وجود إدراج نشاط تجاري أو عدم إجراء مقارنة.
`listing`	object أو null	ما يعرضه الدليل: `name` و`street` و`city` و`state` و`postalCode` و`country` و`fullAddress` و`phones` و`url`. تكون قيمة الحقول التي لا ينشرها الدليل `null`. تكون القيمة `null` عند عدم العثور على إدراج النشاط التجاري.
`syncStatus`	string أو null	حالة مزامنة موقعك على هذا الدليل. تُعيَّن فقط في فحوص `LOCATION_LISTINGS`.

status الخاص بالنتيجة

القيمة	المعنى
`FOUND`	يوجد إدراج للنشاط التجاري على هذا الدليل.
`NOT_FOUND`	تم التحقق من الدليل، ولا يوجد فيه إدراج للنشاط التجاري.
`UNAVAILABLE`	تعذّر التحقق من هذا الدليل هذه المرة. هذا لا يعني عدم وجود إدراج للنشاط التجاري.
`PENDING`	لم يتم التحقق بعد. لا تظهر هذه الحالة إلا أثناء تشغيل الفحص.

accurate

القيمة	المعنى
`true`	إدراج نشاط تجاري عُثر عليه وتطابق جميع تفاصيله التي تم التحقق منها بيانات النشاط التجاري.
`false`	إدراج نشاط تجاري عُثر عليه ويحتوي على حقل واحد غير صحيح على الأقل. اقرأ `accuracy` لمعرفة الحقول غير الصحيحة.
`null`	لا يوجد حكم. إما أنه لم يُعثر على النشاط التجاري، أو أنه عُثر عليه وتم تأكيد وجوده دون التحقق من كل حقل على حدة، كما هو الحال مع بعض الأدلة ومع مساعدي الذكاء الاصطناعي. تُحتسب هذه الحالات ضمن `found` فقط.

accuracy لكل حقل. كل من name وaddress وphone هو كائن يحتوي على status بقيمة ACCURATE أو INACCURATE أو MISSING، وعلى message يشرح الاختلاف، مثل Phone number does not match. تعني MISSING أن الدليل لا يعرض تلك المعلومة، مثل No phone number on the listing. استخدم listing لعرض ما يحتوي عليه الدليل فعليًا بجانب ما كنت تتوقعه.

syncStatus. في فحص LOCATION_LISTINGS، يُستمد الحكم من إدراج النشاط التجاري الفعلي لموقعك بدلًا من المقارنة. يمثّل syncStatus حالة ذلك الإدراج (SYNCED أو COMPLETED أو IN_PROGRESS أو PENDING_APPROVAL أو REQUIRING_ACTION أو FAILED أو AVAILABLE أو CANNOT_SUBMIT)، وهي القيم نفسها المستخدمة في GET /locations/{locationId}/listings/premium. تُحتسب الحالتان SYNCED وCOMPLETED على أنهما دقيقتان.

ملاحظات.

لا يُرجع الفحص إلا للحساب الذي أنشأه. عند استخدام أي معرّف آخر، تُرجع نقطة النهاية 404 مع SY83005.
تعرض بعض الأدلة بيانات دليل آخر. على سبيل المثال، تعرض Uber وWaze وLyft بيانات Google Maps، وتعرض CopilotAI بيانات Bing. تعكس نتائجها نتائج الدليل المصدر، وليس لها url خاص بإدراج نشاط تجاري مستقل.
لا تعتبر UNAVAILABLE نتيجة سلبية: تعذّر التحقق من الدليل، لذا فإن الإجابة غير معروفة.
عندما يكون الفحص نسخة RECENT_SCAN، يمثّل resultsAsOf وقت جمع البيانات، ويمثّل createdAt وقت نسخها إلى حسابك.

Request

curl -X GET 'https://listingsapi.com/api/v4/listings/scans/<scanId>' \  -H "Authorization: API $LISTINGSAPI_KEY"

Run in playground