[DRAFT] API (Search)

Use of the Search API is strongly discouraged at this time. This documentation is intended to help with development of the on-site search pages, and not for external consumers.

The Search private¹ API allows you to filter the card database on certain criteria.

Searchable object types

You can search cards and accessories.

Retrieving the criteria

The criteria files are currently located at the following URLs:

• /static/search/base.en.json
• /static/search/skills.enum.en.json

There is currently no endpoint to retrieve an updated list of criteria files. However, the search UI page does contain this information in "x-panther-index-discovery" meta tags.

Each file has the format:

{
  "criteria": {
    [key]: {
      "type": 1,
      "multi": false,
      "behaviour": {
        ...
      },
      "display_name": "ID"
    },
    ...
}

Criteria objects have the following fields:

Field name	Description
type	Type of accepted value. See type table below.
multi	Always false (for now).
behaviour	Custom attributes for the UI control that represents the criteria. May be missing.
max_length	Only for type 4 criteria (string_max). Maximum length of parameter.
choices	Only for type 1000 criteria (enumerations). {"value": number, "display_name": "some"} OR {"separator": true, "display_name": "some"}
display_name	Localized name of the criteria.

The behaviour field can have the following subfields:

Field name	JSON type	Description
captain_treat_as	?	For internal use.
sort	Boolean	Whether the criteria can be used as a sort field. Will not be present if value is true.
icons	String	Bitsets only. Path prefix for icons images.
compare_type	String	If type is 1000 (ENUM): can be "bit-set" when the control should be displayed as a list of checkboxes. If type is 1 (NUMBER): can be "equal", when range queries (gt/lt) are disallowed.
grouped	Boolean	Will not be present if value is false. Whether the option list has separators.
fts	Boolean	Will not be present if value is false. Whether this string field is connected to a full-text search table (meaning that approximate matches can be returned; e.g. "searching" may be stemmed to "search")

The type field can have the following values:

type	Interpretation	Value to be provided in request
1	Number	{"compare_type": "lt" / "gt" / "eq", "compare_value": number}
2	String	"some"
3	???	Reserved
4	String with max length	"some"
5	???	Reserved
1000	Enumeration	value or [bit1, bit2 ...] (In the second form, functions as an exclusion filter. Will only return results not matching any bit in the set.)

Performing a search

[key] is any key from the criteria object described above. [value] is a payload corresponding to the type of the named criteria as seen in the table above.

POST /api/private/search/cards/results.json
{
    [key]: [value],
    ...,
    "_sort": [key],
}

{
    "result": [
        100011001,
        ...
    ]
}

The returned result list can be used as IDs to query the card API.

Todo

• String and stringmax field types should be merged.
• Request values should be standardized.

---

¹: In this case, private means that functionality and shape of the API may change at any time.