searchCards method

Future<PaginableList<MtgCard>> searchCards(String searchQuery, { RollupMode? rollupMode, SortingOrder? sortingOrder, SortingDirection? sortingDirection, bool? includeExtras, bool? includeMultilingual, bool? includeVariations, int? page, })

GET /cards/search

Returns a PaginableList of all MtgCards that match the specified searchQuery and additional arguments. The searchQuery uses the same fulltext search system as the main site uses.

This method is paginated, returning 175 cards at a time.

If only one card is found, this method will still return a PaginableList.

searchQuery: A fulltext search query. Maximum length: 1000 Unicode characters.

rollupMode: The strategy for omitting similar cards. Defaults to RollupMode.cards.

sortingOrder: The method to sort returned cards. Defaults to SortingOrder.name.

sortingDirection: The direction to sort cards. Defaults to SortingDirection.auto.

includeExtras: If true, extra cards (tokens, planes, etc) will be included. Equivalent to adding include:extras to the fulltext search. Defaults to false.

includeMultilingual: If true, cards in every language supported by Scryfall will be included. Defaults to false.

includeVariations: If true, rare care variants will be included, like the Hairy Runesword. Defaults to false.

page: The page number to return. Defaults to 1.

Implementation

Future<PaginableList<MtgCard>> searchCards(
  String searchQuery, {
  RollupMode? rollupMode,
  SortingOrder? sortingOrder,
  SortingDirection? sortingDirection,
  bool? includeExtras,
  bool? includeMultilingual,
  bool? includeVariations,
  int? page,
}) async {
  final url = Uri.https(
    _baseUrl,
    '/cards/search',
    <String, String?>{
      'q': searchQuery,
      'unique': rollupMode?.name,
      'order': sortingOrder?.name,
      'dir': sortingDirection?.json,
      'include_extras': includeExtras?.toString(),
      'include_multilingual': includeMultilingual?.toString(),
      'include_variations': includeVariations?.toString(),
      'page': page?.toString(),
    }..removeWhere((_, value) => value == null),
  );
  final response = await _httpClient.get(url);

  final json = jsonDecode(response.body) as Map<String, dynamic>;

  if (response.statusCode != 200) {
    throw ScryfallException.fromJson(json);
  }

  return PaginableList<MtgCard>.fromJson(
    json,
    (card) => MtgCard.fromJson(card as Map<String, dynamic>),
  );
}