Method entities.search

הפונקציה מחפשת ב-Knowledge Graph ישויות שתואמות למגבלות.

בקשת HTTP

GET https://kgsearch.googleapis.com/v1/entities:search

פרמטרים של שאילתה

שם הפרמטר סוג תיאור
query string מחרוזת מילולית לחיפוש ב-Knowledge Graph.
ids string רשימה של מזהי ישויות לחיפוש ב-Knowledge Graph. כדי לציין כמה מזהים בבקשת ה-HTTP, צריך לחזור על הפרמטר כתובת URL כמו בדוגמה הבאה: ...?ids=A&ids=B
languages string רשימת קודי השפות (מוגדרים ב-ISO 639) שאיתם רוצים להריץ את השאילתה, למשל 'en'.
types string מגבילה את הישויות שהוחזרו לישויות מהסוגים שצוינו. לדוגמה, אפשר לציין 'אדם' (כפי שמוגדר ב-http://schema.org/Person) כדי להגביל את התוצאות לישויות שמייצגות אנשים. אם ציינת כמה סוגים, ישויות שהוחזרו יכילו אחד או יותר מהסוגים האלה.
indent boolean מאפשרת כניסת פסקה של תוצאות JSON.
prefix boolean מאפשר התאמת קידומת (מחרוזת משנה ראשונית) מול שמות וכינויים של של ישויות. לדוגמה, הקידומת 'Jung' תתאים לישויות ולכינויים בתור 'Jung', 'Jungle' ו-'Jung-ho Kang'.
limit number הגבלת מספר הישויות שיוחזרו. המקסימום הוא 500. ברירת המחדל היא 20. לבקשות עם מגבלות גבוהות יש סיכוי גבוה יותר לסיום הזמן הקצוב.

גוף הבקשה

גוף הבקשה חייב להיות ריק.

גוף התשובה

הודעת תגובה מכילה רשימת ישויות המוצגות בפורמט JSON-LD ותואם ל- סכימות של schema.org (עם תוספים חיצוניים מוגבלים).

בדוגמה הבאה של JSON-LD אפשר לראות את המבנה של גוף התשובה:

{
  "@context": {
    "@vocab": "http://schema.org/",
    "goog": "http://schema.googleapis.com/",
    "resultScore": "goog:resultScore",
    "detailedDescription": "goog:detailedDescription",
    "EntitySearchResult": "goog:EntitySearchResult",
    "kg": "http://g.co/kg"
  },
  "@type": "ItemList",
  "itemListElement": [
    {
      "@type": "EntitySearchResult",
      "result": {
        "@id": "kg:/m/0dl567",
        "name": "Taylor Swift",
        "@type": [
          "Thing",
          "Person"
        ],
        "description": "Singer-songwriter",
        "image": {
          "contentUrl": "https://t1.gstatic.com/images?q=tbn:ANd9GcQmVDAhjhWnN2OWys2ZMO3PGAhupp5tN2LwF_BJmiHgi19hf8Ku",
          "url": "https://en.wikipedia.org/wiki/Taylor_Swift",
          "license": "http://creativecommons.org/licenses/by-sa/2.0"
        },
        "detailedDescription": {
          "articleBody": "Taylor Alison Swift is an American singer-songwriter and actress. Raised in Wyomissing, Pennsylvania, she moved to Nashville, Tennessee, at the age of 14 to pursue a career in country music. ",
          "url": "http://en.wikipedia.org/wiki/Taylor_Swift",
          "license": "https://en.wikipedia.org/wiki/Wikipedia:Text_of_Creative_Commons_Attribution-ShareAlike_3.0_Unported_License"
        },
        "url": "http://taylorswift.com/"
      },
      "resultScore": 4850
    }
  ]
}

שדות תשובה

שם השדה סוג תיאור
@id string ה-URI הקנוני של הישות.
name string שם הישות.
@type array רשימת הסוגים הנתמכים של קובצי schema.org שתואמים לישות.
description string תיאור קצר של הישות.
image URL תמונה שעוזרת לזהות את הישות.
detailedDescription string תיאור מפורט של הישות.
url URL כתובת האתר הרשמית של הישות, אם היא זמינה.
resultScore number מדד שמציין עד כמה הישות התאימה למגבלות הבקשות.

מילות מפתח ב-JSON-LD

למילות מפתח ב-JSON-LD כמו @context , @vocab, @type, או @id, יש לעיין ב מפרט JSON-LD.

תאימות של Schema.org

התשובה משתמשת באוצר המילים שמתארח בכתובת schema.org, עם תוספים מוגבלים (עבור לדוגמה, resultScore) שתואמים לאוצר המילים של schema.org. לפרטים נוספים על התוספים האלה, אפשר לעיין במאמר רשימה של תוספים לסכימה

לכל אחד מהסוגים של Schema.org (כמו Person) והמאפיינים (כמו name) יש URI תואם מלא, כמו בדוגמאות הבאות:

  • אדם -> http://schema.org/Person

  • דבר -> http://schema.org/Thing

  • שם -> http://schema.org/name

  • תיאור -> http://schema.org/description

הסוגים והמאפיינים שמוגדרים כתוספי סכימה של Google יכולים מורחבת בכתובת http://schema.googleapis.com. לדוגמה,

  • EntitySearchתוצאת -> http://schema.googleapis.com/EntitySearchResult
  • detailsDescription -> http://schema.googleapis.com/detailedDescription

המסמכים עבור כל סוג ומאפיין זמינים ב-URI המתאים.

רשימה של תוספי סכימה

תוספי הסכימה שנמצאים בשימוש ב-API הזה מתארחים בכתובת http://schema.googleapis.com כתוספים חיצוניים.

התוסף type ל-Schema.org הוא:

תוספי המאפיינים ל-Schema.org הם: