---
title: "Search Maps"
method: GET
path: "/api/v3/maps"
tags: ["Maps"]
---

# Search Maps

`GET /api/v3/maps`

Search and filter maps with comprehensive filtering options.

## Query parameters

- `code` string, nullable — Filter by map code
- `map_id` integer, nullable — Filter by map ID
- `playtest_status` 'Approved' | 'In Progress' | 'Rejected' | 'null', nullable — Filter by playtest status
- `archived` boolean, nullable — Filter by archived status
- `hidden` boolean, nullable — Filter by hidden status
- `official` boolean, nullable — Filter by official status
- `playtest_thread_id` integer, nullable — Filter by playtest thread ID
- `category` string[], nullable — Filter by category list
- `map_name` string[], nullable — Filter by map name list
- `difficulty_exact` 'Easy' | 'Medium' | 'Hard' | 'Very Hard' | 'Extreme' | 'Hell' | 'null', nullable — Filter by exact difficulty tier
- `difficulty_range_min` 'Easy' | 'Medium' | 'Hard' | 'Very Hard' | 'Extreme' | 'Hell' | 'null', nullable — Filter by minimum difficulty
- `difficulty_range_max` 'Easy' | 'Medium' | 'Hard' | 'Very Hard' | 'Extreme' | 'Hell' | 'null', nullable — Filter by maximum difficulty
- `mechanics` string[], nullable — Filter by mechanics (AND semantics)
- `restrictions` string[], nullable — Filter by restrictions (AND semantics)
- `tags` string[], nullable — Filter by tags (AND semantics)
- `creator_ids` integer[], nullable — Filter by creator user IDs
- `creator_names` string[], nullable — Filter by creator names
- `user_id` integer, nullable — User ID for completion/medal filtering
- `medal_filter` 'All' | 'With' | 'Without' — Medal filter (All/With/Without)
- `completion_filter` 'All' | 'With' | 'Without' — Completion filter (All/With/Without)
- `playtest_filter` 'All' | 'Only' | 'None' — Playtest filter (All/Only/None)
- `minimum_quality` integer, nullable — Minimum average quality rating
- `page_size` integer — Results per page
- `page_number` integer — Page number (1-indexed)
- `sort` string[], nullable — List of 'field:direction' sort keys
- `finalized_playtests` boolean, nullable — Filter finalized playtests
- `return_all` boolean — Return all results without pagination
- `force_filters` boolean — Force filters even with code param

## Response `200`

Request fulfilled, document follows

- MapResponse[]
  - `id` integer, required
  - `code` string, required
  - `map_name` string, required
  - `category` 'Classic' | 'Increasing Difficulty' | 'Other', required
  - `creators` CreatorFull[], required
    - `id` integer, required
    - `is_primary` boolean, required
    - `name` string, required
  - `checkpoints` integer, required
  - `difficulty` 'Easy -' | 'Easy' | 'Easy +' | 'Medium -' | 'Medium' | 'Medium +' | 'Hard -' | 'Hard' | 'Hard +' | 'Very Hard -' | 'Very Hard' | 'Very Hard +' | 'Extreme -' | 'Extreme' | 'Extreme +' | 'Hell', required
  - `official` boolean, required
  - `playtesting` 'Approved' | 'In Progress' | 'Rejected', required
  - `archived` boolean, required
  - `hidden` boolean, required
  - `created_at` string, date-time, required
  - `updated_at` string, date-time, required
  - `ratings` number, nullable
  - `playtest` MapPlaytestResponse
    - `thread_id` integer, required
    - `vote_average` number, nullable
    - `vote_count` integer, nullable
    - `voters` integer[], nullable
    - `verification_id` integer, nullable
    - `initial_difficulty` number, required
    - `completed` boolean, required
  - `guides` string[], nullable
  - `raw_difficulty` number, nullable
  - `mechanics` string[]
  - `restrictions` string[]
  - `tags` string[]
  - `description` string, nullable
  - `medals` MedalsResponse
    - `gold` number, required
    - `silver` number, required
    - `bronze` number, required
  - `title` string, nullable
  - `map_banner` string, nullable
  - `time` number, nullable
  - `total_results` integer, nullable
  - `linked_code` string, nullable

## Other responses

- `400` — Bad request syntax or unsupported method

---

[API](https://skmtc.net/genji/apis/genji-shimada-api.md) · [All operations](https://skmtc.net/genji/apis/genji-shimada-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/genji/genji-shimada-api/versions/6db12055b305/schema)