Sri Lanka's biggest classifieds marketplace, as one JSON API

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.

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.

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.

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.

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.

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.

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 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.

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.

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.

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.

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.

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.

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.