kgsearch.entities.search - what format should "ids" parameter take?

Question

The docs for the [Knowledge Graph API][1] are very sparse; they mention I can use "ids" to search for a specific list of entities instead of using a query. I have some entity IDs that were reported by the natural-language API as "mentioned entities" in documents, such as:

kg:/g/11c58ncq2b

When I provide one of these as an "ids" query-string parameter, I get a terse 400:

"code": 400, "message": "Request contains an invalid argument.", "status": "INVALID_ARGUMENT"

Same result if I try to use the bare string "11c58ncq2b" or other variants.

Does anyone know what format is expected here?

Answer 1

The answer turns out to have two parts: one simple, one complex.

The simple: although it's not documented anywhere, stripping the kg: URL scheme from the entity IDs returned by the natural language API turns them into IDs that the kgsearch API can grok. Thus, searching for ID /g/11c58ncq2b will respond with 200 whereas kg:/g/11c58ncq2b will respond with 400,

The complex: it seems that these entity IDs are not consistent between versions of the APIs. Thus, entity IDs returned by v1beta of the natural language API frequently fail to yield any result when I search v1 of the KG API. After learning the format of the ids parameter, my searches still kept returning mostly-empty results. Once I switched to consistently using v1 of all APIs, my searches began to yield useful results.