Search

XIVAPI provides the ability to quickly search all game content via ElasticSearch. This search endpoint only searches game content and not: characters, free companies, linkshells or pvp teams. Those have their own dedicated search endpoints as they relay to Lodestone.

A string or filter is required to search.

Search for something! The Search is multi-content and contains combined data, this means your search request covers a vast amount of selected content (which you can further extend via filters) and results are combined based on best-case matching.

Params

Deprecation Notice:

The method of GET params (show in the table below) for search is now deprecated. While the functionality will never go away and always exist in some capacity, extending filter abilities is no longer supported. If you want uncapped power for search please considering using ElasticSearch Payloads, view the advanced section for more information.

Param Description
indexes

Search a specific series of indexes separated by commas.

Accepts: Achievement, Title, Action, CraftAction, Trait, PvPAction, PvPTrait, Status, BNpcName, ENpcResident, Companion, Mount, Leve, Emote, InstanceContent, Item, Recipe, Fate, Quest, ContentFinderCondition, Balloon, BuddyEquip, Orchestrion, PlaceName, Weather, World, Map, lore_finder

string

The string to search for. The results for this are affected by string_column and string_algo.

string_algo

The search algorithm to use for string matching.

Default: match_phrase_prefix

For more information, read: Term Level Queries on ElasticSearch.

Supported Algorithms:

custom wildcard + fuzzy
custom wildcard
wildcard Post wildcard, eg: Aim*
wildcard_plus Post & Prefix wildcard, eg: *Aim*
fuzzy Perform a fuzzy search. Fuzziness = 5
term Match whole words by keyword terms.
prefix Match a prefix, like a cheap auto-complete
match Perform a match query.
match_phrase Perform a match phrase query
match_phrase_prefix Perform a match phrase prefix query
multi_match Match against multiple string columns, separated by a comma.
query_string Perform a query string, this has lots of logic!
string_column

The column to use in string searches.

page Set the search results page, this controls pagination in the response
sort_field Sort results by a specific field, you will loose scoring.
sort_order Order the sort_field by a specific direction, either: asc or desc.
limit Limit the number of results to show. (from 1 to 100)

Filters

Filters can be performed in the following format:

[FieldName][Operator][Value], eg: LevelItem>=150

You can provide a comma separated list of filters as an "AND" exclusive query, eg:

filters=LevelItem>35,LevelItem<=40,ClassJobCategory.ID=38

eg: http://cafemaker.wakingsands.com/search?filters=LevelItem>35,LevelItem<=40,ClassJobCategory.ID=38

Accepted Operators:

Operator Information
= Performs a `match`, eg: LevelItem=50 means only items that are level 50.
> Performs a "Greater than" `range` query. (gt)
>= Performs a "Greater than or equal to" `range` query. (gte)
< Performs a "Less than" `range` query. (gt)
<= Performs a "Less than" `range` query. (gt)
|= Performs a "IN" `list` query.
! Performs a "must exist" query.
!! Performs a "must_not exist" query.

Search for lore! This is a special built search endpoint which searches a string through various lore specific content. The endpoint has all the same features as the /search endpoint including Advanced ElasticSearch Queries.

The "Data" column provides more information about the source of the lore entry such as the content name and icon. You can access this using the "columns" query parameter, for example:

columns=Data

eg: http://cafemaker.wakingsands.com/lore?string=legendary&columns=Text,Data

The current content included in lore are:

  • Cutscene Subtitles
  • All Quest Dialogue and text data
  • Item Descriptions
  • Leve text data
  • FATE text data
  • NPC Yells
  • NPC Balloon tooltips
  • Instance Content and Public content text data
  • Achievement Descriptions
  • Default Talk entries
  • Event Item Help text
  • Mounts and Minion text
  • Status descriptions
  • Triple Triad Card text

If you want more, just hop on discord!


Advanced ElasticSearch Queries

As search just uses the powerful ElasticSearch, you can infact just provide an Elastic Search valid JSON query to the endpoint as the "body" param and it will be processed. This bypasses all of the normal GET attributes you see above (excluding: indexes) and allows you complete control over how you build the Elastic Query.

You can learn more about Elastic Search queries via the Query DSL Documentation

How do I get this awesome power!?

By simply sending a JSON payload with the ElasticSearch query in the "body" field, search will switch to advanced mode whenever it sees a query in the "body" field. You can test your DSL using the Search Playground.

The payload is in the following format:

{
    "body": {
        // The Elastic Search payload
    },
    "indexes": "comma,list,of,indexes",
}

Here is a full working example:

{
  "indexes": "item,achievement,instantcontent",
  "body": {
    "query": {
      "bool": {
        "must": [
          {
            "wildcard": {
              "NameCombined_en": "*aiming*"
            }
          }
        ],
        "filter": [
          {
            "range": {
              "ItemSearchCategory.ID": {
                "gt": "1"
              }
            }
          },
          {
            "range": {
              "LevelItem": {
                "gte": "100"
              }
            }
          },
          {
            "range": {
              "LevelItem": {
                "lte": "125"
              }
            }
          }
        ]
      }
    },
    "from": 0,
    "size": 10,
    "sort": [
      {
        "LevelItem": "desc"
      }
    ]
  }
}