# /gsmarena/devices/search

`POST /api/gsmarena/devices/search`

Price: 1 credit

Search the GSMArena device catalogue with the site's own Phone Finder filters: manufacturer, market status, cellular bands, SIM format, body shape and materials, ingress rating, operating system, chipset, memory card slot, display technology, cutout, cameras, sensors, connectivity, battery and charging, plus numeric ranges for year, price, dimensions, weight, cores, RAM, storage, display and camera figures. Returns device cards with the numeric id, page URL, name, manufacturer, model and image.

## How to use it

Use this to find devices by their properties. Every filter narrows the set, and they combine, so an over-specified request legitimately comes back empty rather than as an error. `query` matches free text against the whole spec sheet, which is how you reach features that have no dedicated filter (`periscope`, `under display camera`). Sizes are in the source's own units: RAM and storage in megabytes, display resolution as a total pixel count, video as a line count. GSMArena serves only the most popular slice of a match set, so a broad filter set returns a sample and not the whole catalogue — narrow the filters when you need one particular device. Feed the returned id into the device endpoint for the full specification sheet.

## Parameters

- `access-token` (string, required)

## Request body

- `timeout` (integer) — Max scrapping execution timeout (in seconds) (default: 300; min: 20; max: 1500)
- `count` (integer, required) — Max number of devices to return (min: 1; max: 70)
- `query` (string, nullable) — Free text matched against the whole specification sheet (examples: "periscope", "under display camera"; minLength: 1)
- `colour` (string, nullable) — Keep only devices offered in a colour whose name contains this text (minLength: 1)
- `brands` (array) — Keep only devices of these manufacturers (default: []; one of: "Acer", "alcatel", "Allview", "Amazon", "Amoi", "Apple", "Archos", "Asus", "AT&T", "Benefon", "BenQ", "BenQ-Siemens", "Bird", "BlackBerry", "Blackview", "BLU", "Bosch", "BQ", "Casio", "Cat", "Celkon", "Chea", "Coolpad", "Cubot", "Dell", "Doogee", "EE", "Emporia", "Energizer", "Ericsson", "Eten", "Fairphone", "Fujitsu Siemens", "Garmin-Asus", "Gigabyte", "Gionee", "Google", "Haier", "HMD", "Honor", "HP", "HTC", "Huawei", "i-mate", "i-mobile", "Icemobile", "Infinix", "Innostream", "iNQ", "Intex", "itel", "Jolla", "Karbonn", "Kyocera", "Lava", "LeEco", "Lenovo", "LG", "Maxon", "Maxwest", "Meizu", "Micromax", "Microsoft", "Mitac", "Mitsubishi", "Modu", "Motorola", "MWg", "NEC", "Neonode", "NIU", "Nokia", "Nothing", "Nvidia", "O2", "OnePlus", "Oppo", "Orange", "Oscal", "Oukitel", "Palm", "Panasonic", "Pantech", "Parla", "Philips", "Plum", "Posh", "Prestigio", "QMobile", "Qtek", "Razer", "Realme", "RugOne", "Sagem", "Samsung", "Sendo", "Sewon", "Sharp", "Siemens", "Sonim", "Sony", "Sony Ericsson", "Spice", "T-Mobile", "TCL", "Tecno", "Tel.Me.", "Telit", "Thuraya", "Toshiba", "Ulefone", "Umidigi", "Unnecto", "Vertu", "verykool", "vivo", "VK Mobile", "Vodafone", "Wiko", "WND", "XCute", "Xiaomi", "XOLO", "Yezz", "Yota", "YU", "ZTE")
- `availability` (array) — Keep only devices in these market states (default: []; one of: "Available", "Coming soon", "Discontinued", "Rumored")
- `bands_2g` (array) — Keep only devices supporting these GSM bands (default: []; one of: "GSM 850", "GSM 900", "GSM 1800", "GSM 1900")
- `bands_3g` (array) — Keep only devices supporting these HSPA bands (default: []; one of: "HSPA 850", "HSPA 900", "HSPA 1700", "HSPA 1900", "HSPA 2100")
- `bands_4g` (array) — Keep only devices supporting these LTE band numbers, or `any` for any LTE at all (default: []; one of: "any", "1", "2", "3", "4", "5", "6", "7", "8", "9", "10", "11", "12", "13", "14", "17", "18", "19", "20", "21", "22", "23", "24", "25", "26", "27", "28", "29", "30", "31", "32", "33", "34", "35", "36", "37", "38", "39", "40", "41", "42", "43", "44", "46", "66", "71")
- `bands_5g` (array) — Keep only devices supporting these 5G NR band numbers, or `any` for any 5G at all (default: []; one of: "any", "1", "2", "3", "5", "7", "8", "12", "14", "18", "20", "25", "28", "29", "30", "34", "38", "39", "40", "41", "48", "50", "51", "65", "66", "70", "71", "74", "75", "76", "77", "78", "79", "80", "81", "82", "83", "84", "86", "89", "90", "91", "92", "93", "94", "95", "257", "258", "260", "261")
- `sim_types` (array) — Keep only devices taking these SIM formats (default: []; one of: "Mini-SIM (regular size)", "Micro-SIM", "Nano-SIM")
- `form_factors` (array) — Keep only devices of these body shapes (default: []; one of: "Bar", "Flip up", "Flip down", "Slide", "Swivel", "Watch", "Other", "Foldable")
- `protection_ratings` (array) — Keep only devices carrying these ingress-protection or MIL-STD ratings (default: []; one of: "IP5x", "IP6x", "IPx5", "IPx6", "IPx7", "IPx8", "IPx9", "MIL-STD-810D", "MIL-STD-810F", "MIL-STD-810G", "MIL-STD-810H")
- `body_backs` (array) — Keep only devices with these back materials (default: []; one of: "Plastic", "Aluminum", "Glass", "Ceramic")
- `body_frames` (array) — Keep only devices with these frame materials (default: []; one of: "Plastic", "Aluminum", "Stainless steel", "Ceramic", "Titanium")
- `chipsets` (array) — Keep only devices built on these chipsets (default: []; one of: "Snapdragon 8 Elite Gen 5", "Snapdragon 8 Gen 5", "Snapdragon 8 Elite", "Snapdragon 8 Gen 3", "Snapdragon 8s Gen 4", "Snapdragon 8s Gen 3", "Snapdragon 8 Gen 2", "Snapdragon 8+ Gen 1", "Snapdragon 8 Gen 1", "Snapdragon 7 Gen 4", "Snapdragon 7+ Gen 3", "Snapdragon 7 Gen 3", "Snapdragon 7s Gen 4", "Snapdragon 7s Gen 3", "Snapdragon 7s Gen 2", "Snapdragon 7+ Gen 2", "Snapdragon 7 Gen 1", "Snapdragon 6 Gen 4", "Snapdragon 6 Gen 3", "Snapdragon 6s Gen 4", "Snapdragon 6s Gen 3", "Snapdragon 6 Gen 1", "Snapdragon 4 Gen 5", "Snapdragon 4 Gen 4", "Snapdragon 4 Gen 2", "Snapdragon 4s Gen 2", "Snapdragon 4 Gen 1", "Snapdragon 888+", "Snapdragon 888", "Snapdragon 870", "Snapdragon 865+", "Snapdragon 865", "Snapdragon 860", "Snapdragon 855+", "Snapdragon 855", "Snapdragon 845", "Snapdragon 835", "Snapdragon 821", "Snapdragon 820", "Snapdragon 782", "Snapdragon 780", "Snapdragon 778G", "Snapdragon 768", "Snapdragon 765G", "Snapdragon 750", "Snapdragon 732", "Snapdragon 730G", "Snapdragon 730", "Snapdragon 720", "Snapdragon 712", "Snapdragon 710", "Snapdragon 695", "Snapdragon 690", "Snapdragon 685", "Snapdragon 680", "Snapdragon 675", "Snapdragon 670", "Snapdragon 665", "Snapdragon 662", "Snapdragon 660", "Snapdragon 652", "Snapdragon 650", "Snapdragon 636", "Snapdragon 632", "Snapdragon 630", "Snapdragon 625", "Snapdragon 480", "Snapdragon 460", "Snapdragon 450", "Snapdragon 439", "Snapdragon 435", "Snapdragon 430", "Snapdragon 429", "Snapdragon 425", "Snapdragon 215", "Exynos 2600", "Exynos 2500", "Exynos 2400", "Exynos 2400e", "Exynos 2200", "Exynos 2100", "Exynos 1680", "Exynos 1580", "Exynos 1480", "Exynos 1380", "Exynos 1280", "Exynos 1080", "Exynos 990", "Exynos 980", "Exynos 880", "Exynos 850", "Exynos 9825", "Exynos 9820", "Exynos 9810", "Exynos 9611", "Exynos 9610", "Exynos 8895", "Exynos 8890", "Exynos 7904", "Exynos 7884", "Exynos 7870", "Exynos 7580", "Exynos 7420", "Dimensity 9500", "Dimensity 9500s", "Dimensity 9400+", "Dimensity 9400", "Dimensity 9400e", "Dimensity 9300+", "Dimensity 9300", "Dimensity 9200", "Dimensity 9000", "Dimensity 8500", "Dimensity 8450", "Dimensity 8400", "Dimensity 8350", "Dimensity 8300", "Dimensity 8250", "Dimensity 8200", "Dimensity 8100", "Dimensity 8050", "Dimensity 8020", "Dimensity 8000", "Dimensity 7400X", "Dimensity 7400", "Dimensity 7360", "Dimensity 7300X", "Dimensity 7300", "Dimensity 7200", "Dimensity 7100", "Dimensity 7050", "Dimensity 7030", "Dimensity 7020", "Dimensity 6400", "Dimensity 6300", "Dimensity 6100", "Dimensity 6080", "Dimensity 6020", "Dimensity 1300", "Dimensity 1200", "Dimensity 1100", "Dimensity 1080", "Dimensity 1000", "Dimensity 920", "Dimensity 900", "Dimensity 820", "Dimensity 810", "Dimensity 800", "Dimensity 720", "Dimensity 700", "Helio G200", "Helio G100", "Helio G99", "Helio G96", "Helio G95", "Helio G91", "Helio G90T", "Helio G88", "Helio G85", "Helio G81 Ultra", "Helio G80", "Helio G70", "Helio G35", "Helio P90", "Helio P70", "Helio P65", "Helio P60", "Helio P35", "Helio P25", "Helio P23", "Helio P22", "Helio P20", "Helio P10", "Helio A22", "Helio X25", "Helio X20", "Helio X10", "Kirin 9030 Pro", "Kirin 9020", "Kirin T92A", "Kirin 9010", "Kirin 9000S", "Kirin 9000e", "Kirin 9000", "Kirin 990", "Kirin 985", "Kirin 980", "Kirin 970", "Kirin 960", "Kirin 810", "Kirin 820 5G", "Kirin 710A", "Kirin 710", "Kirin 659")
- `main_camera_counts` (array) — Keep only devices with this many rear cameras (default: []; one of: "One", "Two", "Three", "Four or more")
- `camera_flashes` (array) — Keep only devices with these rear flash types (default: []; one of: "LED", "Dual-LED", "Xenon")
- `fingerprints` (array) — Keep only devices with a fingerprint reader in these positions (default: []; one of: "Yes (any type)", "Front-mounted", "Rear-mounted", "Side-mounted", "Top-mounted", "Under display")
- `wlan` (array) — Keep only devices supporting these Wi-Fi generations (default: []; one of: "Wi-Fi 4 (802.11n)", "Wi-Fi 5 (802.11ac)", "Wi-Fi 6 (802.11ax)", "Wi-Fi 7 (802.11be)")
- `bluetooth` (array) — Keep only devices supporting these Bluetooth versions (default: []; one of: "Any Bluetooth", "Bluetooth 4.0", "Bluetooth 4.1", "Bluetooth 4.2", "Bluetooth 5.0", "Bluetooth 5.1", "Bluetooth 5.2", "Bluetooth 5.3", "Bluetooth 5.4", "Bluetooth 6.0")
- `keyboard` (string, nullable) — Keep only devices with or without a QWERTY keyboard (one of: "With QWERTY", "Without QWERTY")
- `os` (string, nullable) — Keep only devices running this operating system family (one of: "Feature phones", "Android", "iOS", "KaiOS", "Windows Phone", "Symbian", "RIM", "Bada", "Firefox")
- `card_slot` (string, nullable) — Keep only devices with this kind of memory card slot (one of: "Yes (any type)", "Yes (dedicated)", "No")
- `display_tech` (string, nullable) — Keep only devices with this display panel technology (one of: "IPS", "Any OLED", "LTPO OLED")
- `display_cutout` (string, nullable) — Keep only devices with this front camera cutout style (one of: "No", "Yes", "Punch hole")
- `usb_type` (string, nullable) — Keep only devices with this USB connector (one of: "Any USB-C", "USB-C 3.0 and higher")
- `dual_sim` (boolean) — Keep only dual-SIM devices (default: false)
- `esim` (boolean) — Keep only devices with an eSIM (default: false)
- `hdr_display` (boolean) — Keep only devices with an HDR display (default: false)
- `billion_colour_display` (boolean) — Keep only devices with a 1 billion colour display (default: false)
- `main_camera_ois` (boolean) — Keep only devices with optical stabilisation on the main camera (default: false)
- `telephoto_camera` (boolean) — Keep only devices with a telephoto camera (default: false)
- `ultrawide_camera` (boolean) — Keep only devices with an ultrawide camera (default: false)
- `multiple_selfie_cameras` (boolean) — Keep only devices with more than one selfie camera (default: false)
- `selfie_camera_ois` (boolean) — Keep only devices with optical stabilisation on the selfie camera (default: false)
- `selfie_flash` (boolean) — Keep only devices with a front-facing flash (default: false)
- `popup_selfie_camera` (boolean) — Keep only devices with a pop-up selfie camera (default: false)
- `under_display_selfie_camera` (boolean) — Keep only devices with a selfie camera under the display (default: false)
- `headphone_jack` (boolean) — Keep only devices with a 3.5 mm headphone jack (default: false)
- `stereo_speakers` (boolean) — Keep only devices with stereo speakers (default: false)
- `accelerometer` (boolean) — Keep only devices with an accelerometer (default: false)
- `gyroscope` (boolean) — Keep only devices with a gyroscope (default: false)
- `compass` (boolean) — Keep only devices with a compass (default: false)
- `proximity_sensor` (boolean) — Keep only devices with a proximity sensor (default: false)
- `barometer` (boolean) — Keep only devices with a barometer (default: false)
- `heart_rate_sensor` (boolean) — Keep only devices with a heart rate sensor (default: false)
- `gps` (boolean) — Keep only devices with GPS (default: false)
- `nfc` (boolean) — Keep only devices with NFC (default: false)
- `infrared_port` (boolean) — Keep only devices with an infrared port (default: false)
- `fm_radio` (boolean) — Keep only devices with an FM radio (default: false)
- `silicon_carbon_battery` (boolean) — Keep only devices with a silicon-carbon battery (default: false)
- `removable_battery` (boolean) — Keep only devices with a removable battery (default: false)
- `has_editorial_review` (boolean) — Keep only devices GSMArena has published an editorial review for (default: false)
- `year_min` (integer, nullable) — Earliest announcement year (min: 1994; max: 2100)
- `year_max` (integer, nullable) — Latest announcement year (min: 1994; max: 2100)
- `price_eur_min` (integer, nullable) — Lowest launch price in EUR (min: 0)
- `price_eur_max` (integer, nullable) — Highest launch price in EUR (min: 0)
- `height_mm_min` (integer, nullable) — Lowest body height in millimetres (min: 0)
- `height_mm_max` (integer, nullable) — Highest body height in millimetres (min: 0)
- `width_mm_min` (integer, nullable) — Lowest body width in millimetres (min: 0)
- `width_mm_max` (integer, nullable) — Highest body width in millimetres (min: 0)
- `thickness_mm_min` (integer, nullable) — Lowest body thickness in millimetres (min: 0)
- `thickness_mm_max` (integer, nullable) — Highest body thickness in millimetres (min: 0)
- `weight_g_min` (integer, nullable) — Lowest weight in grams (min: 0)
- `weight_g_max` (integer, nullable) — Highest weight in grams (min: 0)
- `cpu_cores_min` (integer, nullable) — Lowest CPU core count (min: 1)
- `cpu_cores_max` (integer, nullable) — Highest CPU core count (min: 1)
- `ram_mb_min` (integer, nullable) — Lowest RAM in megabytes, so 12 GB is 12000 (min: 0)
- `storage_mb_min` (integer, nullable) — Lowest built-in storage in megabytes, so 512 GB is 512000 (min: 0)
- `display_pixels_min` (integer, nullable) — Lowest display resolution as a total pixel count, so 1080x2400 is 2592000 (min: 0)
- `display_pixels_max` (integer, nullable) — Highest display resolution as a total pixel count (min: 0)
- `display_inches_min` (number, nullable) — Smallest display diagonal in inches (min: 0)
- `display_inches_max` (number, nullable) — Largest display diagonal in inches (min: 0)
- `display_density_min` (integer, nullable) — Lowest pixel density in ppi (min: 0)
- `display_density_max` (integer, nullable) — Highest pixel density in ppi (min: 0)
- `refresh_rate_min` (integer, nullable) — Lowest display refresh rate in Hz (min: 0)
- `main_camera_mp_min` (integer, nullable) — Lowest main camera resolution in megapixels (min: 0)
- `aperture_f_min` (number, nullable) — Lowest main camera aperture f-number, so f/1.8 is 1.8 (min: 0)
- `aperture_f_max` (number, nullable) — Highest main camera aperture f-number (min: 0)
- `video_lines_min` (integer, nullable) — Lowest main camera video resolution in lines, so 4K is 2160 (min: 0)
- `selfie_camera_mp_min` (integer, nullable) — Lowest selfie camera resolution in megapixels (min: 0)
- `battery_mah_min` (integer, nullable) — Lowest battery capacity in mAh (min: 0)
- `battery_mah_max` (integer, nullable) — Highest battery capacity in mAh (min: 0)
- `wired_charging_w_min` (integer, nullable) — Lowest wired charging power in watts (min: 0)
- `wired_charging_w_max` (integer, nullable) — Highest wired charging power in watts (min: 0)
- `wireless_charging_w_min` (integer, nullable) — Lowest wireless charging power in watts (min: 0)
- `wireless_charging_w_max` (integer, nullable) — Highest wireless charging power in watts (min: 0)
- `sort` (string) — Result ordering (default: "Popularity"; one of: "Popularity", "Price", "Weight", "Camera resolution", "Battery capacity")

## Response

### 200 — Successful Response

- `@type` (string) (default: "GsmarenaDeviceCard")
- `id` (integer, required)
- `url` (string, required)
- `name` (string, required)
- `brand` (string, nullable)
- `model` (string, nullable)
- `image` (string, nullable)
- `summary` (string, nullable)
- `announced` (string, nullable)

## Errors

### 422 — Validation Error

The request body did not validate

What to do: Check the fields against this schema. A URN with the wrong prefix is the most common cause.

- `detail` (array)
  - `loc` (array, required)
  - `msg` (string, required)
  - `type` (string, required)
  - `input` (any)
  - `ctx` (object)

### 408

The request ran past its time limit

What to do: Raise `timeout` in the request body, up to the maximum this endpoint documents. Lowering `count` or turning off the `with_*` flags also helps, because less work finishes sooner.

### 412

The entity was not found, or a precondition failed

What to do: Retrying will not help: either the entity does not exist, or the input points at a different one.

### 429

Too many requests: a rate limit or a usage window is exhausted

What to do: When the response carries an X-Retry-After header, wait that many seconds and retry: the same number is in the body as `detail.retry_after`, and the limit clears once that window passes. The message in the body names the limit that was hit.

### 500

Something broke on our side

What to do: Retrying will not help. If it keeps happening, send us the X-Request-ID from the response headers.

### 529

Rate limit reached, or the endpoint is overloaded

What to do: Wait at least 30 seconds, then retry.

## Response envelope

Success: Array of objects (may be empty if no results)

Error: Error may coexist with partial results if it occurs mid-execution. Check X-Error header and status code.

Every response carries these headers:

- `X-Error` — Error message text (present only on error)
- `X-Request-ID` — Unique request identifier
- `X-Execution-Time` — Execution time in seconds
- `X-Result-Count` — How many records the body carries. 0 means an empty result, which is a normal answer and not by itself an error. A non-zero count can come back together with X-Error when the failure happened partway through — read this header and X-Error independently.
- `X-Total-Available-Results` — How many records exist for this query, when the endpoint can say. On a `dry_run` request this is the answer and the body is empty. It saturates: the endpoint's documented maximum means 'at least that many', any smaller number is exact.
- `X-Warning` — Present when the request body carried keys this endpoint does not document. They were ignored, so any filter you meant to apply through them did not apply. Check the spelling against this schema and retry.
- `X-Retry-After` — Seconds to wait before retrying. Present only on 429.