ikman.lk API & Scraper
The ikman API returns Sri Lanka's largest classifieds marketplace as clean JSON, in four actions: search, listing, categories and locations.
🤖 Using an AI assistant? Copy this link into ChatGPT / Claude / Cursor — it reads every endpoint and parameter instantly and tells you if this API fits your use case.
ikman.lk is where Sri Lanka actually buys and sells: on 2026-10-02 its live catalogue held 353,089 ads — 89,274 under Vehicles, 64,450 Electronics, 63,452 Property, 58,911 Mobiles, 19,435 Home & Garden, 15,408 Services, 14,066 Business & Industry, 9,798 Jobs, 5,701 Animals, 5,220 Hobby/Sport/Kids, 3,520 Fashion & Beauty and 613 Agriculture, split 340,036 for sale, 12,224 for rent, 546 wanted to buy and 284 wanted to rent. search narrows that by free-text keywords, any of 299 categories, any of Sri Lanka's 27 districts or 304 cities, and the offer direction, and sorts by price or posting date in either direction. Every row carries the ad id and slug, the public ad URL, the title, the price in rupees with the exact string ikman itself prints, the category, the district and the city, the item condition where the category has one, when the ad was posted and when it expires, the source's own summary chips (mileage, body type, condition for a car), whether the row is a paid placement, up to full-size and thumbnail photo URLs, and the advertiser's public contact card — and, where the ad belongs to a dealer, that dealer's shop page. listing adds the complete ad text as the advertiser wrote it, every photo, the category's own attribute list (year, mileage, bedrooms, employer, job type, salary band), the ad's view count, and for a job the salary range and the application deadline. categories returns all 299 live categories as a two-level tree under 17 sections; locations returns all 331 districts and cities, optionally with the boundary polygons ikman publishes. Verified on 2026-10-02: 29 of 29 live checks behaved as expected on two separate runs — 18 successes and 11 error cases each landing on the right code — all 12 top-level categories returned rows and resolved their first ad to a full detail record with the id coming back unchanged, all 12 exposed filters measurably narrowed a same-run control, 8 of 8 round-trips by id, slug and URL resolved to the same record, and on 296 priced rows the parsed amount matched the string ikman prints beside it 296 of 296, with zero mismatches. No ikman account — one ReefAPI key and the standard { ok, data, meta, error } envelope.
What is actually on the site — live ad counts on 2026-10-02
These are counts read off the live index, one call each, not estimates. They move as ads are posted and expire; every search response carries the matching total in the response body, plus ikman's own live total for each section, district and offer direction.
| section | category id | live ads | price published? |
|---|---|---|---|
| Vehicles (cars, vans, bikes, three wheelers, parts) | 391 | 89,274 | yes, in LKR |
| Electronics (computers, TVs, cameras, audio) | 428 | 64,450 | yes, in LKR |
| Property (land, houses, apartments, rentals) | 409 | 63,452 | yes, in LKR |
| Mobiles (phones, tablets, accessories) | 2000 | 58,911 | yes, in LKR |
| Home & Garden (furniture, appliances) | 444 | 19,435 | yes, in LKR |
| Services | 537 | 15,408 | often not — a service ad may be quote-only |
| Business & Industry | 535 | 14,066 | yes, in LKR |
| Jobs | 700 | 9,798 | a salary RANGE, not a price |
| Animals (pets and livestock) | 489 | 5,701 | yes, in LKR |
| Hobby, Sport & Kids | 503 | 5,220 | yes, in LKR |
| Fashion & Beauty | 470 | 3,520 | yes, in LKR |
| Agriculture | 587 | 613 | yes, in LKR |
That is 12 of the 17 top-level sections; the categories action lists all 299 categories with their parents and ids. The leaves are narrow and usually what you want to query directly — measured the same day: Mobile Phones 53,462 · Auto Parts & Accessories 29,485 · Land For Sale 27,514 · Motorbikes & Scooters 26,096 · Houses For Sale 18,415 · Cars 10,766 · Vehicle Rentals 9,036 · House Rentals 4,396 · Three Wheelers 3,809 · Apartments For Sale 3,598 · Lorries & Trucks 1,110 · Vans 1,044. Add a district and it narrows again: Cars in Colombo district was 6,732. 🔴 Two things worth knowing before you build against the tree. ikman still ships legacy categories in its own table that have no live ads — "Houses" (411) and "Land" (417) both measured 0, and a second "Mobile Phones" under Electronics (429) measured 15 against the live one's 53,462 — so check the count, not just the name. And whatever total a query reports, only the first 10,000 rows are reachable: page 400 answers and page 401 does not, measured on three different result sets including one reporting 14,124 pages. The API publishes reachable_results beside total_results and flags total_truncated_by_ceiling. The whole catalogue splits 340,036 for sale, 12,224 for rent, 546 wanted to buy and 284 wanted to rent.
Real request and response JSON
Captured from the indexed primary action, search, on .
{
"method": "POST",
"url": "https://api.reefapi.com/ikman/v1/search",
"headers": {
"x-api-key": "$REEF_KEY",
"content-type": "application/json"
},
"body": {
"query": "car",
"max_results": 20
}
}{
"ok": true,
"meta": {
"api": "ikman",
"endpoint": "search",
"mode": "live",
"latency_ms": 1944.7,
"record_count": 26,
"bytes": 76765,
"cache_hit": false,
"upstream_requests": 1,
"source_url": "https://api.ikman.lk/v1/serp?query=car&page=1",
"charged_credits": 1,
"version": "1.0.0",
"request_id": "d83a7568f0c24064",
"queue_ms": 1
},
"data": {
"total_results": 6277,
"reachable_results": 6277,
"reported_page_count": 252,
"reachable_page_count": 252,
"page_ceiling": 400,
"total_truncated_by_ceiling": false,
"page": 1,
"page_size": 25,
"returned": 26,
"promoted_rows": 1,
"leading_promoted_insert": true,
"dropped_non_matching_promoted": 0,
"dropped_non_listing_tiles": 0,
"has_more": true,
"sort_option": "relevance",
"sort_order": "desc",
"catalogue_counts": {
"categories": [
{
"category_id": 391,
"name": "Vehicles",
"count": 89304
},
{
"category_id": 428,
"name": "Electronics",
"count": 63507
},
{
"category_id": 409,
"name": "Property",
"count": 63457
}
],
"cities": [
{
"location_id": 1506,
"name": "Colombo",
"count": 206378
},
{
"location_id": 1577,
"name": "Gampaha",
"count": 55871
},
{
"location_id": 1636,
"name": "Kandy",
"count": 16235
}
],
"listing_types": [
{
"listing_type": "for_sale",
"count": 339102
},
{
"listing_type": "to_buy",
"count": 546
},
{
"listing_type": "for_rent",
"count": 12223
}
]
},
"listings": [
{
"listing_id": "6aad5501f9d21e05033bd45a",
"slug": "rent-a-car-toyota-kdh-for-sale-colombo-119",
"url": "https://ikman.lk/en/ad/rent-a-car-toyota-kdh-for-sale-colombo-119",
"title": "Rent a Car Toyota KDH",
"listing_type": "for_sale",
"status": "published",
"condition": null,
"posted_at": "2026-09-19T19:45:27+05:30",
"expires_at": "2026-11-18T19:45:27+05:30",
"bumped_at": null,
"category_id": 406,
"category_name": "Rentals",
"district_id": 1506,
"district": "Colombo",
"city_id": 2154,
"city": "Kotte",
"highlights": [],
"properties": [],
"promoted": true,
"promotions": {
"top_ad": false,
"bump_up": false,
"urgent_ad": false,
"spotlight": false,
"featured_ad": true
},
"buy_now": false,
"seller": {
"account_id": "513a293cfb549a0b7600000e",
"name": "Ocean Rent A Car",
"account_type": "private",
"phone_numbers": [
"[trimmed-depth]"
],
"email": null,
"email_verified": false,
"chat_enabled": true,
"contact_opt_out": true,
"delivery_methods": [],
"membership_level": "plus",
"paying_member": true,
"authorized_dealer": false,
"featured_member": false
},
"shop": {
"shop_id": "57e358cc2f73e0000176aff6",
"slug": "ocean-rent-a-car",
"name": "Ocean Rent a car",
"tagline": "Car Rental Services",
"description": "The key objective of our mission is to practice good business ethics, build trust and confidence and provide total customer satisfaction. We are committed in giving “value for money” for every single customer that is considered as an utmost priority for the company.",
"url": "https://ikman.lk/en/shop/ocean-rent-a-car",
"location_id": null,
"job_page": false,
"email": "[redacted-email]",
"phone_numbers": [
"[trimmed-depth]"
],
"logo_id": "4b0ace25-2794-4d54-a886-5bce3a37090f",
"logo_base_uri": "https://i.ikman-st.com/u"
},
"price": 12500,
"price_min": null,
"price_max": null,
"price_currency": "LKR",
"price_currency_raw": "Rs",
"price_display": "Rs 12,500",
"price_label": "Price",
"price_kind": "fixed",
"price_display_source_echo": "Rs 12,500",
"price_display_matches_info": true,
"image_count": 4,
"image_ids": [
"1ae2957e-9dd4-4304-a570-80591271b7bb",
"f9e112fb-aa93-4bb3-b8ab-bf035e54f528",
"52626f4a-6e4c-4c41-9651-6a0fff5d34cb"
],
"images": [
"https://i.ikman-st.com/rent-a-car-toyota-kdh-for-sale-colombo-119/1ae2957e-9dd4-4304-a570-80591271b7bb/780/585/cropped.jpg",
"https://i.ikman-st.com/rent-a-car-toyota-kdh-for-sale-colombo-119/f9e112fb-aa93-4bb3-b8ab-bf035e54f528/780/585/cropped.jpg",
"https://i.ikman-st.com/rent-a-car-toyota-kdh-for-sale-colombo-119/52626f4a-6e4c-4c41-9651-6a0fff5d34cb/780/585/cropped.jpg"
],
"image_thumbnails": [
"https://i.ikman-st.com/rent-a-car-toyota-kdh-for-sale-colombo-119/1ae2957e-9dd4-4304-a570-80591271b7bb/158/88/cropped.jpg",
"https://i.ikman-st.com/rent-a-car-toyota-kdh-for-sale-colombo-119/f9e112fb-aa93-4bb3-b8ab-bf035e54f528/158/88/cropped.jpg",
"https://i.ikman-st.com/rent-a-car-toyota-kdh-for-sale-colombo-119/52626f4a-6e4c-4c41-9651-6a0fff5d34cb/158/88/cropped.jpg"
],
"image": "https://i.ikman-st.com/rent-a-car-toyota-kdh-for-sale-colombo-119/1ae2957e-9dd4-4304-a570-80591271b7bb/780/585/cropped.jpg",
"image_thumbnail": "https://i.ikman-st.com/rent-a-car-toyota-kdh-for-sale-colombo-119/1ae2957e-9dd4-4304-a570-80591271b7bb/158/88/cropped.jpg",
"image_base_uri": "https://i.ikman-st.com",
"image_url_template": "https://i.ikman-st.com/rent-a-car-toyota-kdh-for-sale-colombo-119/<image_id>/<width>/<height>/cropped.jpg"
},
{
"listing_id": "6abef4bd37fdaeb23feb0170",
"slug": "rent-a-car-mitsubishi-montero-for-sale-gampaha-210",
"url": "https://ikman.lk/en/ad/rent-a-car-mitsubishi-montero-for-sale-gampaha-210",
"title": "Rent a car - Mitsubishi Montero",
"listing_type": "for_sale",
"status": "published",
"condition": null,
"posted_at": "2026-10-02T05:33:10+05:30",
"expires_at": "2026-12-01T05:33:10+05:30",
"bumped_at": null,
"category_id": 406,
"category_name": "Rentals",
"district_id": 1577,
"district": "Gampaha",
"city_id": 2282,
"city": "Delgoda",
"highlights": [],
"properties": [],
"promoted": false,
"promotions": {
"top_ad": false,
"bump_up": false,
"urgent_ad": false,
"spotlight": false,
"featured_ad": false
},
"buy_now": false,
"seller": {
"account_id": "6022186da808bf5063a11fb0",
"name": "Avotas Auto Fleet",
"account_type": "private",
"phone_numbers": [
"[trimmed-depth]",
"[trimmed-depth]"
],
"email": null,
"email_verified": true,
"chat_enabled": true,
"contact_opt_out": true,
"delivery_methods": [],
"membership_level": "premium",
"paying_member": true,
"authorized_dealer": false,
"featured_member": false
},
"shop": {
"shop_id": "60238c5a3ba2850001a466f7",
"slug": "avotas-tours",
"name": "Avotas Auto Fleet",
"tagline": "Rent a Car & Hiring",
"description": "We provide the most professional, informative, loyal and dedicated service in the industry. For every individual, we will work as hard as we can to help them achieve their tasks. We love to help you find a solution that can become a life changer. We believe that our business can be successful for generations only if we continue a Tradition of Trust and proceed with it continuously.",
"url": "https://ikman.lk/en/shop/avotas-tours",
"location_id": 2282,
"job_page": false,
"email": "[redacted-email]",
"phone_numbers": [
"[trimmed-depth]"
],
"logo_id": "68a3cd6c-d194-4a24-92fc-2ef05c61bb18",
"logo_base_uri": "https://i.ikman-st.com/u"
},
"price": 14000,
"price_min": null,
"price_max": null,
"price_currency": "LKR",
"price_currency_raw": "Rs",
"price_display": "Rs 14,000",
"price_label": "Price",
"price_kind": "fixed",
"price_display_source_echo": "Rs 14,000",
"price_display_matches_info": true,
"image_count": 4,
"image_ids": [
"5915e295-c462-46e5-98f5-6f0b330eaeab",
"84b63485-b677-48db-b2ac-eea847b1d470",
"19ddb4c8-7b93-4011-87bc-29f61eabeb9b"
],
"images": [
"https://i.ikman-st.com/rent-a-car-mitsubishi-montero-for-sale-gampaha-210/5915e295-c462-46e5-98f5-6f0b330eaeab/780/585/cropped.jpg",
"https://i.ikman-st.com/rent-a-car-mitsubishi-montero-for-sale-gampaha-210/84b63485-b677-48db-b2ac-eea847b1d470/780/585/cropped.jpg",
"https://i.ikman-st.com/rent-a-car-mitsubishi-montero-for-sale-gampaha-210/19ddb4c8-7b93-4011-87bc-29f61eabeb9b/780/585/cropped.jpg"
],
"image_thumbnails": [
"https://i.ikman-st.com/rent-a-car-mitsubishi-montero-for-sale-gampaha-210/5915e295-c462-46e5-98f5-6f0b330eaeab/158/88/cropped.jpg",
"https://i.ikman-st.com/rent-a-car-mitsubishi-montero-for-sale-gampaha-210/84b63485-b677-48db-b2ac-eea847b1d470/158/88/cropped.jpg",
"https://i.ikman-st.com/rent-a-car-mitsubishi-montero-for-sale-gampaha-210/19ddb4c8-7b93-4011-87bc-29f61eabeb9b/158/88/cropped.jpg"
],
"image": "https://i.ikman-st.com/rent-a-car-mitsubishi-montero-for-sale-gampaha-210/5915e295-c462-46e5-98f5-6f0b330eaeab/780/585/cropped.jpg",
"image_thumbnail": "https://i.ikman-st.com/rent-a-car-mitsubishi-montero-for-sale-gampaha-210/5915e295-c462-46e5-98f5-6f0b330eaeab/158/88/cropped.jpg",
"image_base_uri": "https://i.ikman-st.com",
"image_url_template": "https://i.ikman-st.com/rent-a-car-mitsubishi-montero-for-sale-gampaha-210/<image_id>/<width>/<height>/cropped.jpg"
},
{
"listing_id": "6abeab6b941f8820a50127f7",
"slug": "rent-a-car-mitsubishi-montero-for-sale-colombo-90",
"url": "https://ikman.lk/en/ad/rent-a-car-mitsubishi-montero-for-sale-colombo-90",
"title": "Rent a Car-Mitsubishi Montero",
"listing_type": "for_sale",
"status": "published",
"condition": null,
"posted_at": "2026-10-02T01:44:53+05:30",
"expires_at": "2026-12-01T01:44:53+05:30",
"bumped_at": null,
"category_id": 406,
"category_name": "Rentals",
"district_id": 1506,
"district": "Colombo",
"city_id": 1508,
"city": "Battaramulla",
"highlights": [],
"properties": [],
"promoted": false,
"promotions": {
"top_ad": false,
"bump_up": false,
"urgent_ad": false,
"spotlight": false,
"featured_ad": false
},
"buy_now": false,
"seller": {
"account_id": "52a3ee130a52ac9c3800193d",
"name": "viraj",
"account_type": "private",
"phone_numbers": [
"[trimmed-depth]"
],
"email": null,
"email_verified": false,
"chat_enabled": true,
"contact_opt_out": true,
"delivery_methods": [],
"membership_level": "plus",
"paying_member": true,
"authorized_dealer": false,
"featured_member": false
},
"shop": {
"shop_id": "5805a0c0a1278600010f79fc",
"slug": "asia-express-rent-a-car",
"name": "ASIA EXPRESS RENT A CAR",
"tagline": "If service counts, count on us!",
"description": "Welcome To ASIA EXPRESS RENT A CAR ASIA EXPRESS RENT A CAR is a cab service in Sri Lanka and aims to provide world-class taxi services at the most economical price in Colombo, Gurgaon & Faridabad city that it enters We provide 24 hour service, Transportation to and from anywhere, Clean, Comfortable, Modern Vehicles, Timely, Dependable Service, Flat Rates and Metered Trips, Special Rate for Airport, Multilingual Drivers, Transport Lorry Service, Non A/C Vans, Front A/C, Dual A/C Van, Wedding Cars, Expert Driver. \n\nOver many years’ experience and the large pool of fleet we offer full customized ",
"url": "https://ikman.lk/en/shop/asia-express-rent-a-car",
"location_id": null,
"job_page": false,
"email": "[redacted-email]",
"phone_numbers": [
"[trimmed-depth]"
],
"logo_id": "16587d2c-d94c-41c4-a9e3-181951ca521b",
"logo_base_uri": "https://i.ikman-st.com/u"
},
"price": 550000,
"price_min": null,
"price_max": null,
"price_currency": "LKR",
"price_currency_raw": "Rs",
"price_display": "Rs 550,000",
"price_label": "Price",
"price_kind": "fixed",
"price_display_source_echo": "Rs 550,000",
"price_display_matches_info": true,
"image_count": 2,
"image_ids": [
"922cf497-7ec3-4dfc-86b1-f25401fd0da2",
"c3471893-f02f-4365-b11e-b082ed4a07fc"
],
"images": [
"https://i.ikman-st.com/rent-a-car-mitsubishi-montero-for-sale-colombo-90/922cf497-7ec3-4dfc-86b1-f25401fd0da2/780/585/cropped.jpg",
"https://i.ikman-st.com/rent-a-car-mitsubishi-montero-for-sale-colombo-90/c3471893-f02f-4365-b11e-b082ed4a07fc/780/585/cropped.jpg"
],
"image_thumbnails": [
"https://i.ikman-st.com/rent-a-car-mitsubishi-montero-for-sale-colombo-90/922cf497-7ec3-4dfc-86b1-f25401fd0da2/158/88/cropped.jpg",
"https://i.ikman-st.com/rent-a-car-mitsubishi-montero-for-sale-colombo-90/c3471893-f02f-4365-b11e-b082ed4a07fc/158/88/cropped.jpg"
],
"image": "https://i.ikman-st.com/rent-a-car-mitsubishi-montero-for-sale-colombo-90/922cf497-7ec3-4dfc-86b1-f25401fd0da2/780/585/cropped.jpg",
"image_thumbnail": "https://i.ikman-st.com/rent-a-car-mitsubishi-montero-for-sale-colombo-90/922cf497-7ec3-4dfc-86b1-f25401fd0da2/158/88/cropped.jpg",
"image_base_uri": "https://i.ikman-st.com",
"image_url_template": "https://i.ikman-st.com/rent-a-car-mitsubishi-montero-for-sale-colombo-90/<image_id>/<width>/<height>/cropped.jpg"
}
],
"query": "car",
"filters": {
"query": "car"
}
}
}What the ikman.lk API does
| Action | Description | Concrete use case | Key params |
|---|---|---|---|
| search | Search ikman.lk classifieds. Needs at least one of `query` (keywords), `category` (a numeric id from the `categories` action) or `location` (a numeric id from the `locations` action); any combination also works, and `listing_type`, `sort`, `order` and `page` narrow or reorder it. Every response also carries `catalogue_counts` — the source's live totals per category, city and offer type. 🔴 They follow the id filters (`category`, `location`, `listing_type`) and IGNORE `query`: measured, `query=toyota` (10 465 matches) still reported 89 274 for category 391, while `category=392` reported 6 732 for Colombo, which is the real Cars-in-Colombo figure. So they size a category or district, they do not split your keyword result. 🔴 Page size is fixed by the source at 25 and no override is accepted; a full page measured 25 or 26 rows because the source adds a paid insert at the top. The source reports more pages than it serves, so `reachable_results` caps at 10 000 per query however large `total_results` is. | Price-intelligence teams call search to search ikman.lk classifieds. | query, category, location, listing_type, sort, ... |
| listing | Full detail of one ad by id, slug or URL: the complete description as the advertiser wrote it, every photo at full size and as a thumbnail, the price with the source's own printed string, the category's own attribute list (year, mileage, bedrooms, employer, job type…), the ad's view count, posting and expiry time, the advertiser's public contact card, the dealer page when the ad belongs to one, the job salary band and application deadline when the ad is a vacancy, and the ids of the ads the source itself calls similar. A removed or non-existent ad returns NOT_FOUND. | Classifieds aggregators call listing to get full detail of one ad by id, slug or URL. | listing_id, url |
| categories | The site's live category table — the resolver `search` needs, because `category` takes a numeric id. 299 categories in a two-level tree under 17 top-level sections, each with its parent, its children, the offer directions it accepts and its public URL. | Resale and arbitrage tools call categories to get the site's live category table. | parent, top_level_only |
| locations | The site's live location table — the resolver `search` needs, because `location` takes a numeric id. 331 rows: Sri Lanka's 27 districts and the 304 cities inside them, each with its parent and, on request, the boundary polygon the source publishes. | Lead-generation teams call locations to get the site's live location table. | parent, districts_only, include_geography |
Call search from your stack
curl -X POST https://api.reefapi.com/ikman/v1/search \
-H "x-api-key: $REEF_KEY" \
-H "content-type: application/json" \
-d '{"query":"car","max_results":20}'import requests
r = requests.post(
"https://api.reefapi.com/ikman/v1/search",
headers={"x-api-key": REEF_KEY},
json={
"query": "car",
"max_results": 20
},
)
print(r.json()["data"])const res = await fetch("https://api.reefapi.com/ikman/v1/search", {
method: "POST",
headers: {
"x-api-key": process.env.REEF_KEY,
"content-type": "application/json",
},
body: JSON.stringify({
"query": "car",
"max_results": 20
}),
});
const { ok, data, meta, error } = await res.json();Ask your MCP-connected assistant: call reefapi.ikman.search with {"query":"car","max_results":20}.Who uses this API and why
- Track Sri Lankan vehicle supply and asking prices: 89,274 vehicle ads on 2026-10-02, with Cars, Vans, Three Wheelers, Motorbikes and Lorries as separate categories, each row carrying the rupee price, mileage and body type, and the dealer's shop page where there is one.
- Build a property feed for one district: 63,452 property ads, filterable to any of 27 districts or 304 cities, sorted by price or posting date, with the full ad text, every photo and the lister's contact card from the detail call.
- Watch a used-electronics or mobile market: 58,911 mobile and 64,450 electronics ads, with the site's own condition token (new, used, reconditioned, import) on each row so you can compare like with like.
- Monitor the Sri Lankan job market without a jobs board: 9,798 live vacancies with the salary band, employer, role, job type and application deadline, in English, Sinhala or Tamil as posted.
- Size the market before you enter it: one search call returns ikman's live total for every section and all 311 cities, so you can see where supply actually is — and the offer-direction split tells you where demand is, with 546 wanted-to-buy and 284 wanted-to-rent ads live.
Questions developers ask before integrating
Which currency are the prices in, and how do I know the number is right?
Sri Lankan rupees, and the currency is read off the source rather than assumed from the country. ikman prints its amounts as strings with their own token — "Rs 7,490,000" — so every row returns price as a parsed number, price_currency as LKR, and price_display as the exact string ikman itself prints. ikman also prints the same amount a second time in a separate field on the same row, and the API compares the two for you on every row: price_display_matches_info. Across 296 priced rows in 12 sections it agreed 296 of 296, zero mismatches. If a token ever came back that we do not recognise, price_currency would be null and price_currency_raw would carry the token — we would rather show you an unknown currency than mislabel one.
Why is price null on some ads?
Because those ads genuinely have no price, and a zero would be a lie. Across 312 sampled rows in all 12 top-level sections, 270 carried a price and 42 did not: wanted ads where the poster is buying, service listings quoted on enquiry, and job posts. Each one comes back with price null and the reason in price_kind — not_priced_wanted, not_priced or range. A job is the interesting case: ikman gives a vacancy a salary band rather than a price, so listing returns price_min and price_max with price_label ("Salary per month") and price_kind range — we measured Rs 45,000 - 75,000 on one post — and price stays null, because a band is not a price.
Does a filter actually do anything, or does the site just ignore it?
Every filter we expose was measured against a same-run control, and we ran two controls because one was not enough. Against a 207,308-ad Colombo-district control: category 391 (Vehicles) 49,636, category 392 (Cars) 6,732, for_sale 196,718, to_buy 145, for_rent 10,249, to_rent 196. Against a 10,465-ad keyword control (toyota): Cars 3,265, Colombo 6,632, Gampaha 1,953. Twelve for twelve. One honest-looking non-result is worth explaining: toyota plus category 391 returned the full 10,465, because every toyota ad really is in Vehicles — that is why the second control exists, and both are in our published logs. One filter the site accepts and does nothing with (buy_now, which returns zero everywhere) is deliberately not exposed, because a handle that does nothing is worse than no handle. And an unknown value for listing_type or sort is rejected with INVALID_PARAM rather than passed through.
Can I filter by price range, mileage or condition?
No, and we would rather say so than offer a switch that quietly does nothing. ikman's own data surface takes no price, condition, year or brand parameter. We probed that properly before answering: 7 spellings of a price band, a condition filter, a brand filter, and then 13 different shapes of the structured filter array the source does define — every one was rejected by the source's own validator, and the two endpoints that would publish a filter vocabulary do not exist. So the four handles that do work are the four we offer: keywords, category, location and offer direction. In practice the category tree does most of the work, because ikman's leaves are narrow (Cars 10,766, Three Wheelers 3,809, Houses For Sale 18,415, House Rentals 4,396 and Land For Sale 27,514 are all separate categories), and every row carries the condition and the category's own attributes so you can filter client-side on exactly the values the site published.
How many rows per page, and is it fixed?
Twenty-five, set by the source, and it accepts no override — we tried three spellings and all three were rejected. What you actually get back is 25 or 26: ikman inserts one paid ad at the top of a full page, so a full page measured 26 rows, 25 on one query, 15 on a 15-row result set and 0 past the end. We publish the source's page_size and the real returned count separately rather than printing a page size we did not measure.
What is the paid row at the top of my results?
A placement ikman has sold, and it ignores the sort you asked for. With sort=price and order=asc on Cars, row 0 came back at Rs 15,200,000 while rows 1 to 3 were the genuinely cheapest — measured the same way on all five sort combinations: only the first row sits outside the order. We return ikman's order unchanged, flag the row promoted: true, publish leading_promoted_insert and promoted_rows, and let you drop them with exclude_promoted. Note that a seller re-dating their own ad (ikman's bump) is NOT counted as a paid placement: it changes nothing about position, so it is reported separately as bumped_at.
What do the counts next to my results mean?
They are ikman's live totals for each section, district and offer direction — and they follow the id filters while ignoring your keyword, which is why the field is called catalogue_counts rather than facets. We measured it both ways. Searching toyota matches 10,465 ads, and the block still reported 89,274 for Vehicles and 207,308 for Colombo district, exactly what an unfiltered search for those ids returns. But search Cars (category 392) and the block reports 6,732 for Colombo and 10,757 for-sale, which are the real Cars-in-Colombo and Cars-total figures. So use them to size a category or a district, not to split a keyword search. One search call gives you that for every section and all 311 cities.
What do I get about the advertiser?
What the public ad page itself shows, unmodified: the display name, whether the account is private or a business, the contact numbers ikman publishes with the ad and whether they are verified, the e-mail where there is one, whether chat is enabled, the account's membership level (free, plus, premium) and ikman's own paying-member, authorised-dealer and featured-member flags. The advertiser's own contact-opt-out flag is passed through so you can see what they asked for. The block was present on 312 of 312 search rows and 12 of 12 details. Where the ad belongs to a dealer, you also get that dealer's shop: name, tagline, description, slug and public shop URL — present on 123 of 312 rows, concentrated in vehicles, and null rather than an empty object everywhere else.
What does listing add over a search row?
The complete ad text as the advertiser wrote it — 243 to 842 characters on the property ads we round-tripped, and several thousand on dealer ads, with markup and HTML entities already cleaned out, in English, Sinhala or Tamil exactly as posted — plus every photo at full size and as a thumbnail, the ad's view count (present 12 of 12), the category's own attribute list, and for a vacancy the salary band, the employer, the job type and the application deadline. Category attributes are the big difference: they came back on 11 of 12 details but only 18 of 312 search rows, because ikman attaches most of them to the ad page rather than the result card. One field we will flag against ourselves: ikman has a similar-ads block and it came back empty on all 12 ads we measured, so we return it as an empty list rather than implying it is populated.
Can I resolve an ikman URL directly?
Yes, and that is unusually convenient here. ikman's ad URLs carry a slug and no id, and the source resolves the slug and the 24-character id to the same record — we verified it on the same ad and on 8 round-trips across id, slug and URL, 8 of 8 matching. So you can pass listing_id, the slug, or a full ikman.lk ad URL, and the API checks that the record it got back is the one you asked for before returning it. A removed or non-existent ad — by id or by slug — returns NOT_FOUND rather than a page-shaped success.
How do I find the right category or district id?
Two actions exist for exactly that, and they are the whole tree, not a sample. categories returns all 299 live categories with their parent, their children, the offer directions each one accepts and its public URL, grouped under 17 top-level sections. locations returns all 331 rows: Sri Lanka's 27 districts and the 304 cities inside them — Colombo alone has 51 — and will include the boundary polygon ikman publishes for each if you ask for it (which is most of the payload, so it is off by default). You can also just read category_id, district_id and city_id off any search row; they come back with their names.
Why is condition empty on some ads?
Because ikman only offers a condition where it means something. It came back on 180 of 312 sampled rows — vehicles, electronics and mobiles have it, property, jobs and services do not — and we return null rather than inventing "used". The values are the site's own tokens (new, used, reconditioned, import and so on) and they also appear in the row's highlights, which is ikman's own summary line: for a car that measured as mileage, body type and condition together, e.g. "5,000 km", "Hatchback", "Reconditioned". Highlights were filled on 220 of 312 rows.
What happens if a search genuinely matches nothing?
You get ok with zero rows and total_results 0, because an empty answer is still an answer. There is one trap in this source that we handle for you: on three measured queries ikman reported total 0 and still shipped one row — the paid insert. The site's own total is authoritative, so a paid row inside a zero-match answer is dropped and counted in dropped_non_matching_promoted rather than handed to you as a match. A nonsense keyword returns 0 rows with nothing attached, so the two cases stay distinguishable.
Are jobs and rentals covered properly, or just the for-sale ads?
All four directions, and they are measured separately. The catalogue splits 340,036 for sale, 12,224 for rent, 546 wanted to buy and 284 wanted to rent, and listing_type gets you any one of them: within Colombo district, for_rent narrowed a 207,308-ad control to 10,249 and to_rent to 196. Jobs are a top-level section with 9,798 live posts and their own fields — salary band, employer, role, job type and application deadline. Note that ikman's own vehicle-rental listings sit in a Rentals category and are typed for_sale, so for a rental car you want the category, not the offer direction.