Look up an author or book

Resolves an author or book name to the catalog IDs that search filters take. Returns up to five candidates with the author’s death year (AH) and a match score.

GET/catalog/lookup

Authorization

AuthorizationBearer token · headerrequired

An API key from qaf.ai Settings › API keys.

Query parameters

typestringrequired

Whether the name is an author or a book.

Allowed:authorbook

querystringrequired

The name to resolve, in Arabic or English.

min length 1 · max length 200

localestring

Language of the candidate labels; no other is returned.

default: "en"

Allowed:aren

Responses

200

The candidates for the name.

candidatesobject[]required

Up to five candidates.

max items 5

Show properties

Array of object

Any of:

object

typestringrequired

idintegerrequired

Author ID, for filters.authorIds.

labelstringrequired

The author's name in the requested locale.

deathYearAHinteger | nullrequired

The author's death year in AH, when known.

Show properties

Any of:

integer

integer

null

null

deathInexactLabelstring | nullrequired

A label for an approximate or unknown death year, when deathYearAH is missing or inexact.

Show properties

Any of:

string

string

null

null

matchScorenumberrequired

How closely the name matches the query, from 0 to 1; higher is closer.

min 0 · max 1

object

typestringrequired

idstring<uuid>required

Book ID, for filters.bookIds.

labelstringrequired

The book's title in the requested locale.

authorIdintegerrequired

The author's ID, for filters.authorIds.

authorLabelstringrequired

The author's name in the requested locale.

deathYearAHinteger | nullrequired

The author's death year in AH, when known.

Show properties

Any of:

integer

integer

null

null

deathInexactLabelstring | nullrequired

A label for an approximate or unknown death year, when deathYearAH is missing or inexact.

Show properties

Any of:

string

string

null

null

categoryIdintegerrequired

The book's genre ID. Search filters take the genre's slug.

matchScorenumberrequired

How closely the name matches the query, from 0 to 1; higher is closer.

min 0 · max 1

401

The API key is missing, invalid or revoked.

codestringrequired

Allowed:UNAUTHORIZED

statusintegerrequired

messagestringrequired

403

The key's account can't use the API.

codestringrequired

Allowed:FORBIDDEN

statusintegerrequired

messagestringrequired

422

A field is invalid. data.fieldErrors lists the problems by field.

codestringrequired

Allowed:INPUT_VALIDATION_FAILED

statusintegerrequired

messagestringrequired

dataobject

Show properties

formErrorsstring[]required

fieldErrorsobjectrequired

429

Too many requests; data.reason says which limit was reached. For minute, the account's requests per minute, retry after Retry-After seconds. For day, the account's daily search cap, Retry-After is the time until the cap resets. For invalid_keys, the key doesn't exist or was revoked and this address has sent too many such keys, so fix the key rather than retrying. The X-RateLimit headers describe the account's minute window, so an invalid_keys refusal, which comes before any key is known, has none.

codestringrequired

Allowed:RATE_LIMITED

statusintegerrequired

messagestringrequired

dataobject

Show properties

retryAfterintegerrequired

Seconds to wait.

min 0

reasonstringrequired

Which limit was reached: minute, the account's requests per minute; day, its searches per day; or invalid_keys, a key that doesn't exist or was revoked, from an address that has sent too many such keys.

Allowed:minutedayinvalid_keys

500

Something went wrong on our side.

codestringrequired

Allowed:INTERNAL_SERVER_ERROR

statusintegerrequired

messagestringrequired

503

Qaf could not complete the request in time, or a service it relies on is unavailable. Retry shortly.

codestringrequired

Allowed:SERVICE_UNAVAILABLE

statusintegerrequired

messagestringrequired

Try it

Server

Base URLCustom base URLOverrides the selected server when set.

Authorization

Bearer tokenRemember on this deviceInclude my values in samples

Parameters

typequery*Whether the name is an author or a book.queryquery*The name to resolve, in Arabic or English.localequeryLanguage of the candidate labels; no other is returned.

Request

curl -X GET 'https://api.qaf.ai/v1/catalog/lookup?type=author&query=%D8%A7%D8%A8%D9%86%20%D8%AA%D9%8A%D9%85%D9%8A%D8%A9' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Accept: application/json'

const response: Response = await fetch("https://api.qaf.ai/v1/catalog/lookup?type=author&query=%D8%A7%D8%A8%D9%86%20%D8%AA%D9%8A%D9%85%D9%8A%D8%A9", {
  method: "GET",
  headers: {
    "Authorization": "Bearer YOUR_TOKEN",
    "Accept": "application/json"
  }
});

import requests

response = requests.get(
    "https://api.qaf.ai/v1/catalog/lookup?type=author&query=%D8%A7%D8%A8%D9%86%20%D8%AA%D9%8A%D9%85%D9%8A%D8%A9",
    headers={
        "Authorization": "Bearer YOUR_TOKEN",
        "Accept": "application/json"
    },
)

Response

{
  "candidates": [
    {
      "type": "author",
      "id": 54,
      "label": "Ibn Taymiyya",
      "deathYearAH": 728,
      "deathInexactLabel": null,
      "matchScore": 1
    },
    {
      "type": "author",
      "id": 988,
      "label": "Majd al-Din Ibn Taymiyya",
      "deathYearAH": 652,
      "deathInexactLabel": null,
      "matchScore": 0.95
    }
  ]
}

{
  "code": "UNAUTHORIZED",
  "status": 401,
  "message": "Invalid API key."
}

{
  "code": "FORBIDDEN",
  "status": 403,
  "message": "This Qaf account can't use the API."
}

{
  "code": "INPUT_VALIDATION_FAILED",
  "status": 422,
  "message": "The request has invalid fields.",
  "data": {
    "formErrors": [
      "string"
    ],
    "fieldErrors": {
      "property1": [
        "string"
      ],
      "property2": [
        "string"
      ]
    }
  }
}

{
  "code": "RATE_LIMITED",
  "status": 429,
  "message": "Too many requests. Try again later.",
  "data": {
    "retryAfter": 0,
    "reason": "minute"
  }
}

{
  "code": "INTERNAL_SERVER_ERROR",
  "status": 500,
  "message": "Something went wrong on our side. Try again later."
}

{
  "code": "SERVICE_UNAVAILABLE",
  "status": 503,
  "message": "Qaf could not complete this request. Try again shortly."
}