{ "openapi": "3.0.0", "info": { "version": "1.0", "title": "Motory API", "description": "Motory API for Saudi car marketplace and Jordan car market data from motory.com: KSA and Jordan used cars for sale with prices, VIN and seller contacts, new car prices, makes and models, car filters with counts, dealers, car offers and financing, new car comparison, a Saudi automotive business directory, car news, videos and fuel prices, in English and Arabic. Car API, used car API and Motory scraper alternative for Riyadh, Jeddah, Dammam and Amman. Build car listing and car price apps similar to Syarah, Haraj, YallaMotor, OpenSooq, Dubizzle and CarSwitch.", "x-category": "Data", "x-long-description": "# 🚗 Motory API\n\n| Feature | Details |\n| --- | --- |\n| **Last Updated** | **October 12, 2026** |\n| 🇸🇦 Market Coverage | Saudi Arabia (prices in SAR) and Jordan (prices in JOD), each with its own inventory and ids; Saudi cities such as Riyadh, Jeddah, Dammam, Khobar, Makkah and Madinah, and Jordan cities such as Amman |\n| 🔍 Used Car Search | 26 parameters on `searchUsedCars`: 21 filters (make, model, city, year, price, body type, fuel type, transmission, mileage, colour, origin, electric range, financing, priced listings only, seller type, dealer, price collection and keyword) and 7 sort orders: featured, newest, oldest, mileage and price in both directions |\n| 📋 Full Listing Details | Specs, VIN, gallery, price, seller phone and WhatsApp numbers, inspection reports and related cars and offers for every used listing |\n| 🆕 New Car Catalogue | New car prices by model year and grade, specs, features, selling companies with phone and WhatsApp numbers, financing, make line-ups with starting and top prices, 5 sort orders and archived model years |\n| ⚖️ Car Comparison | Two new cars side by side across 6 spec categories, plus the cars most often compared with a car and the most compared cars of the week |\n| 💳 Finance and Offers | Finance providers by make, new cars by finance provider, and current car offers and financing deals with terms, dates, the cars on offer, monthly instalment, down payment and eligibility terms |\n| 🎛️ Filter Options with Live Counts | Used and new car filter options with result counts that narrow as you add filters: cities, makes, models, years, price bands, body, fuel, transmission, mileage, colour, origin, electric range, seller types and dealers |\n| 🏷️ Dealers and Showrooms | Showcased dealers with stock counts and a preview of their cars; dealer phones, WhatsApp, showroom map locations and branch count |\n| 🔗 URL Front Doors | Paste a motory.com search or listing link and get the results or the full record; identify any motory.com link with its page type and ids |\n| 🔎 Site Search and Suggestions | Keyword search across used cars, new cars, offers, the directory, news and videos; typed text to make, model and year suggestions with ids |\n| 🛠️ Saudi Business Directory | Saudi workshops, spare parts shops, car washes, tyre shops, inspection centres, rentals and showrooms by name, address, city, make, service, amenity, opening day and open now, with contacts, opening hours and branches |\n| 📰 Car News and Videos | News by category, author, tag and make, sorted newest, oldest or most read; full articles and author profiles; car videos by category, make, model and model year with playable MP4 links |\n| ⛽ Fuel Prices | Retail fuel prices per litre by fuel grade for Saudi Arabia and Jordan, with the month of the last update |\n| 🌐 English and Arabic | Names, labels and content in English or Arabic with `lang`; news articles are separate English and Arabic collections |\n| ⚡ API Type | Fast REST API via RapidAPI |\n\nBring Motory (motory.com) car marketplace data from Saudi Arabia and Jordan into your application: search used cars for sale with 21 filters and open each listing with its specs, VIN, price, inspection reports and seller contacts, browse the new car catalogue with prices, grades, selling companies and financing, compare two new cars, list dealers, car offers and finance providers, read filter options with live result counts, search Saudi automotive businesses such as workshops, spare parts shops and car washes, and read car news, car videos and fuel prices, in English and Arabic.\n\n## Overview\n\nThe Motory API is an unofficial car marketplace data API for Motory (motory.com), the car marketplace for Saudi Arabia and Jordan. It is not affiliated with Motory. Choose a market with `country` (`sa` for Saudi Arabia, `jo` for Jordan) and a language with `lang` (`en` or `ar`), get make and model ids from the reference endpoints, then search used cars for sale and the new car catalogue with the filters and sort orders shoppers use on the site, and open each car with its specs, price, seller or selling companies and financing. List dealers and their stock, current car offers and financing deals, compare two new cars, or paste a motory.com link and get its record. In Saudi Arabia, search the automotive business directory of workshops, spare parts shops, car washes, rentals and showrooms. Read car news, car videos and fuel prices in both markets.\n\nIt is built for car listing and car price comparison apps, used car price research and valuation models, dealer and inventory monitoring, new car price tracking, car finance and offer comparison, automotive lead generation, automotive business directories and car media products across Saudi Arabia (KSA) and Jordan.\n\n## Key Features\n\n- Get make and model ids for used and new cars, and a make's current new car line-up with starting and top prices by model.\n- Read the used and new car filter options with result counts that narrow as you add filters, before you build a filter panel.\n- Search used cars for sale with 21 filters and 7 sort orders: make, model, city, year, price, body, fuel, transmission, mileage, colour, origin, electric range, seller type (dealer or private seller), dealer, financing, priced listings only, price-reduced and lease-transfer collections, and a free-text keyword.\n- Sort a used car search by price, cheapest or most expensive first, when it matches up to 50 listings; narrow a larger search with the price bands of `getUsedCarFilters` first.\n- Open a used listing with specs, VIN, gallery, price, seller phone and WhatsApp numbers, inspection reports and related cars.\n- Search the new car catalogue by make, model, year, price, body, fuel, transmission, origin, electric range, financing and finance provider, with 5 sort orders, and reach archived model years.\n- Open a new car with specs, features, model years and grades, selling companies with phone numbers, and financing.\n- Compare two new cars across 6 spec categories, and find the cars most often compared with a car or the most compared this week.\n- Search all of Motory by keyword across used cars, new cars, offers, the directory, news and videos, and turn typed text into make, model and year suggestions with ids.\n- Paste a motory.com search or listing link to get the results or the record, or identify any motory.com link with its page type and ids.\n- List showcased dealers with stock counts and car previews, and open a dealer's phones, WhatsApp, showroom locations and branches.\n- List current car offers and financing deals by make or offering company, and open an offer with its terms, dates, cars, monthly instalment, down payment and eligibility terms.\n- Search the Saudi automotive business directory by name, address, city, make served, service, amenity, opening day, open now, provider kind and official agent flag, and open businesses, companies and branches with contacts and opening hours.\n- Read car news by category, author, tag or make, newest, oldest or most read first, open full articles and author profiles, and list the most-read articles.\n- List car videos by category, make, model and model year, and open a video with its playable MP4 link and related videos, news, cars and offers.\n- Read retail fuel prices per litre for Saudi Arabia and Jordan.\n\n## Available Data\n\nUsed car data covers the listing id, title, make, model and year with their ids and logos, price with its currency and price note, financing availability and financing company, mileage band, city, transmission, publish date, seller id and name, dealer or private seller, phone and WhatsApp numbers, VAT and warranty notes, photos and the listing's share link. The full listing adds the gallery, overview specs, description, VIN, the seller section, inspection reports, related used and new cars and offers.\n\nNew car data covers model year and grade with the other years and grades of the model, price and financing, overview specs, description, features, the selling companies with their price, phone and WhatsApp numbers, offers and related new and used cars. Make line-ups carry each model's body type, model year, starting and top price, minimum monthly instalment and images, with the make's selling companies and their contacts. Comparisons carry both cars and their spec rows by category, and compare suggestions carry the cars to compare.\n\nReference data covers makes and models with ids and logos, used and new car filter options with result counts, finance providers and per-litre fuel prices by grade. Dealer data covers dealer ids and names, city, featured flag, stock count, a car preview, phones, WhatsApp, showroom map locations, branch count and share link. Offer data covers the title, start and end dates, days left, images, description, benefits, makes covered, the offering company, the cars on offer with their offer price, monthly instalment and down payment, and the eligibility terms an application-form offer states.\n\nDirectory data covers Saudi businesses, multi-branch companies and branches with English and Arabic names and addresses, city, coordinates, phones, WhatsApp, website, images, services, amenities, the makes served, official agent flag, weekly opening hours and holidays, plus the service, amenity, city and make vocabularies. Editorial data covers news categories, article cards, full articles with HTML body, gallery, author, tags, related articles and related new cars, author profiles with biography, credentials and social links, author tags, video categories and videos with playable MP4 link, description and related videos, news, new cars and offers.\n\n## Reference\n\n### `listMakes` (`/makes`)\n\nList car makes with their ids and logos: the makes that have used cars for sale, or the full new car brand catalogue. Call it first in most workflows, in the market you will search; a make id feeds `listModels`, `searchUsedCars`, `searchNewCars` and the filter endpoints.\n\n### `listModels` (`/models`)\n\nList one make's models with their ids, for used cars for sale or for the new car model catalogue. Take a `make_id` from `listMakes`; the model id feeds `searchUsedCars` and `searchNewCars`.\n\n### `getNewCarLineup` (`/new-car-lineup`)\n\nShow a make's current new car line-up: one row per model with starting and top price, body type, model year, images and minimum monthly instalment, plus the make's selling companies with their contacts, optionally narrowed to one or more body types. Use it for a brand page or a quick price overview, then follow a row's `model_id` into `searchNewCars`.\n\n### `getUsedCarFilters` (`/used-car-filters`)\n\nGet the used car filter options with result counts: cities, makes, models, years, price bands, body, fuel, transmission, mileage, colour, origin, electric range, seller types and dealers. The counts narrow with the same filters as `searchUsedCars`, except keyword and price collection. Use it to build a filter panel and pass the option values back to `searchUsedCars`.\n\n### `getNewCarFilters` (`/new-car-filters`)\n\nGet the new car filter options with result counts: makes, models, model years, price bands, body, fuel, transmission, origin and electric range, narrowed by the `searchNewCars` filters except the finance provider. Pass the option values back to `searchNewCars`.\n\n### `listFinanceProviders` (`/finance-providers`)\n\nList the finance providers that finance new cars, optionally for one make. A provider id is the `finance_provider_id` that `searchNewCars` filters by; use it to find the cars one bank or finance company covers.\n\n### `getFuelPrices` (`/fuel-prices`)\n\nRead the retail fuel prices per litre for Saudi Arabia or Jordan, one entry per fuel grade, with the month of the last update. It takes only `country` and `lang`, so no id is needed from another call.\n\n## Used Cars\n\n### `searchUsedCars` (`/used-cars`)\n\nSearch used cars for sale in Saudi Arabia or Jordan with 21 filters: make, model, city, year, price, body, fuel, transmission, mileage, colour, origin, electric range, seller type, dealer, financing, priced listings only, price collection (cars with prices, price-reduced cars, lease-transfer cars, financing) and a keyword matched in the selected language. Choose one of 7 sort orders: featured, newest, oldest, mileage in both directions, or price in both directions. The price orders sort a search that matches up to 50 listings; narrow a larger search with `min_price` and `max_price` and the price bands of `getUsedCarFilters`. Rows carry the price, financing, mileage, city, seller and contact numbers; open one in `getUsedCarDetails`.\n\n### `getUsedCarDetails` (`/used-car-details`)\n\nRead one used car listing in full: specs, VIN, gallery, price, the seller's phone and WhatsApp numbers, inspection reports and related cars and offers. Take a `vehicle_id` from a `searchUsedCars` row.\n\n### `searchUsedCarsByUrl` (`/used-cars-by-url`)\n\nPaste a motory.com used car search page link, such as a make, model, city, year or financing page, and get the same results as `searchUsedCars` with the filters in the link applied. The response lists the filters it applied with `searchUsedCars` parameter names, and every link parameter it did not apply with the reason.\n\n### `getUsedCarDetailsByUrl` (`/used-car-details-by-url`)\n\nPaste a motory.com used car listing link, for example the share link of a `searchUsedCars` row, and get the same full listing as `getUsedCarDetails` without looking up the id first.\n\n## New Cars\n\n### `searchNewCars` (`/new-cars`)\n\nSearch the new car catalogue with prices by make, model, year, price, body, fuel, transmission, origin, electric range, financing and finance provider, in 5 sort orders: featured, newest or oldest model year, and cheapest or most expensive first. An explicit year reaches older model years that are no longer sold. Take ids from `listMakes`, `getNewCarFilters` and `listFinanceProviders`; open a row in `getNewCarDetails`.\n\n### `getNewCarDetails` (`/new-car-details`)\n\nRead one new car, a model year and grade, in full: specs, features, the model's other years and grades, the selling companies with their prices, phone and WhatsApp numbers, financing, offers and related cars. Take a `vehicle_id` from a `searchNewCars` row.\n\n### `searchNewCarsByUrl` (`/new-cars-by-url`)\n\nPaste a motory.com new car search page link, such as a make, model, year or financing page, and get the same results as `searchNewCars` with the filters in the link applied, plus the filters applied and every link parameter not applied with the reason.\n\n### `getNewCarDetailsByUrl` (`/new-car-details-by-url`)\n\nPaste a motory.com new car page link and get the same full car as `getNewCarDetails` without looking up the id first.\n\n### `compareNewCars` (`/compare-new-cars`)\n\nCompare two new cars side by side: both cars with their prices, and spec-by-spec rows in 6 categories (technical specifications, safety, luxury, convenience and comfort, entertainment and technology, specifications), plus similar comparisons. Take two ids from `searchNewCars` rows or `getCompareSuggestions`.\n\n### `getCompareSuggestions` (`/compare-suggestions`)\n\nFind new cars to compare: the cars most often compared with a given new car, or without one the market's most compared cars this week. Pass two ids on to `compareNewCars`.\n\n## Search\n\n### `searchMotory` (`/search`)\n\nSearch all of Motory by keyword across used cars, new cars, offers, the Saudi business directory, news and videos, or within one section and one category of it, 10 rows per page. Use it for a site-wide search box; open a row with the detail endpoint its section points to.\n\n### `getSearchSuggestions` (`/search-suggestions`)\n\nTurn typed text into make, model and year suggestions that carry ids, for used or new cars. Use it for a search box type-ahead, then pass the `make_id` and `model_id` to `searchUsedCars` or `searchNewCars`.\n\n### `resolveUrl` (`/resolve-url`)\n\nIdentify any ksa.motory.com or jo.motory.com link and get its page type with the ids it carries: vehicle, make, model, year, city, dealer, offer, news, video, category, author, directory service, business or company, including make pages, site search pages and information pages. Use the ids with the matching detail or list endpoint.\n\n## Dealers\n\n### `listDealers` (`/dealers`)\n\nList the marketplace's showcased car dealers and showrooms, in Saudi Arabia the featured dealers, optionally for one make, one city or one dealer, with each dealer's stock count and a preview of their cars. Take filter ids from the response's own filter lists or `listMakes`; open a dealer in `getDealerDetails`.\n\n### `getDealerDetails` (`/dealer-details`)\n\nRead one dealer's profile: phones, WhatsApp, showroom map locations, branch count and stock count. List the dealer's cars with `searchUsedCars` and its `dealer_id` filter.\n\n## Offers\n\n### `listCarOffers` (`/offers`)\n\nList current car offers and financing deals published by distributors and dealers, optionally for one make or one offering company. Use it to track promotions and finance deals across brands; open an offer in `getCarOfferDetails`.\n\n### `getCarOfferDetails` (`/offer-details`)\n\nRead one car offer: terms, start and end dates, the offering company, the cars on offer with monthly instalment and down payment, and, for an application-form offer, the eligibility terms it states such as covered makes, models, years, cities, payment types and minimum monthly income.\n\n## Directory\n\n### `searchDirectory` (`/directory-search`)\n\nSearch Saudi automotive businesses and companies, such as workshops, spare parts shops, car washes, tyre shops, rentals and showrooms, by name, address, city, make served, service, amenity, opening day, open now, provider kind and official agent flag, sorted newest, oldest or by name. Take ids from `listDirectoryCities`, `listDirectoryMakes`, `listDirectoryServices` and `listDirectoryAmenities`.\n\n### `getDirectoryBusinessDetails` (`/directory-business-details`)\n\nRead one directory business in full: contacts, address, coordinates, images, services, amenities, weekly opening hours and the makes it serves. Take a `business_id` from a `searchDirectory` business row.\n\n### `getDirectoryCompanyDetails` (`/directory-company-details`)\n\nRead one multi-branch directory company in full: contacts, images, services, amenities, opening hours, makes served and branch count. Take a `company_id` from `searchDirectoryCompanies` or `searchDirectory`; list its locations with `listDirectoryCompanyBranches`.\n\n### `searchDirectoryCompanies` (`/directory-companies`)\n\nList or name-search the multi-branch companies of the Saudi automotive directory by English or Arabic name, sorted newest, oldest or by name. Open a company in `getDirectoryCompanyDetails` or its locations in `listDirectoryCompanyBranches`.\n\n### `listDirectoryCompanyBranches` (`/directory-branches`)\n\nList the branches of one directory company with address, coordinates, phones, weekly opening hours and each branch's own services, amenities and makes, optionally by city, service, amenity, make, address, opening day or open now. Use it to find the nearest or open branch of a chain.\n\n### `listDirectoryServices` (`/directory-services`)\n\nList every service category of the Saudi automotive directory, such as spare parts, car wash, tyres, inspection, rentals and showrooms, with English and Arabic names. Use an id as `service_id` on `searchDirectory` and `listDirectoryCompanyBranches`.\n\n### `listDirectoryAmenities` (`/directory-amenities`)\n\nList every amenity a directory provider can offer, such as a waiting area, parking, Wi-Fi and payment methods, with English and Arabic names. Use an id as `amenity_id` on `searchDirectory` and `listDirectoryCompanyBranches`.\n\n### `listDirectoryCities` (`/directory-cities`)\n\nList the Saudi cities of the business directory with English and Arabic names and slugs. Use an id as `city_id` on `searchDirectory` and `listDirectoryCompanyBranches`.\n\n### `listDirectoryMakes` (`/directory-makes`)\n\nList the makes a directory provider can serve, including trucks, motorcycles and heavy equipment, with English and Arabic names, logo and link. Use an id as `make_id` on `searchDirectory` and `listDirectoryCompanyBranches`.\n\n## News\n\n### `listNewsCategories` (`/news-categories`)\n\nList the news categories of a market and language, such as Car News, Local News, Car Reports and Car Advice. Pass a category id to `getNewsByCategory`, or as a filter on `searchNews`, `getNewsByAuthor` and `getNewsByTag`.\n\n### `getNewsByCategory` (`/category-news`)\n\nList the news articles of one category, newest, oldest or most read first, optionally for one author, one make or a title text, as article cards with title, date, author, image and excerpt. Open a row in `getNewsDetails`.\n\n### `searchNews` (`/news-search`)\n\nSearch news articles by a keyword matched against their titles, newest, oldest or most read first, optionally in one category, by one author or about one make. Open a row in `getNewsDetails`.\n\n### `getNewsDetails` (`/news-details`)\n\nRead one news article in full: HTML body, gallery, author, tags, related articles and related new cars. Take a `news_id` from any article list.\n\n### `getNewsAuthorDetails` (`/author-details`)\n\nRead a news author's profile: biography, job title, credentials, social links and topics. Take an `author_id` from an article row; list the author's articles with `getNewsByAuthor` and tags with `listNewsAuthorTags`.\n\n### `getNewsByAuthor` (`/author-news`)\n\nList one author's news articles, newest, oldest or most read first, optionally in one category, about one make or matching a title text. Use it for author pages and author research.\n\n### `listNewsAuthorTags` (`/author-tags`)\n\nList the tags an author writes under, such as makes, body types and topics, optionally narrowed by a name fragment. Pass a tag id to `getNewsByTag`.\n\n### `getNewsByTag` (`/tag-news`)\n\nList the news articles carrying one tag, a topic such as SUV or a make such as Toyota, newest, oldest or most read first, optionally in one category, by one author or matching a title text. A make id from `listMakes` in the same market works as a tag id, so this is also news by make.\n\n### `listMostReadNews` (`/most-read-news`)\n\nList the market's most-read news articles as a short list of article cards. Use it for a trending or popular news panel.\n\n## Videos\n\n### `listVideoCategories` (`/video-categories`)\n\nList the video categories of a market, such as Reviews, Motory Studio, One Minute Brief and Electric Cars. Pass a category id to `listVideos`.\n\n### `listVideos` (`/videos`)\n\nList the marketplace's car videos, newest or oldest first, optionally for one category, make, model or model year; with no filter the featured videos come in a list of their own. Open a video in `getVideoDetails`.\n\n### `getVideoDetails` (`/video-details`)\n\nRead one video: playable MP4 link, description, category and related videos, news, new cars and offers. Take a `video_id` from a `listVideos` row or its featured videos.\n\n## Plan Access\n\nEvery endpoint in the table is free to try on Basic. Pro includes car reference data, used car listings, the new car catalogue and the marketplace search tools. Ultra adds dealers and offers, and car news and videos. Mega includes every endpoint, including the Saudi automotive business directory. Basic is a trial of the whole API, so Pro and Ultra do not include every endpoint Basic can try; if you need every endpoint, choose Mega. A green tick means the endpoints in that row are available on the plan; a red cross means they are not.\n\n| Feature | Endpoints | Basic | Pro | Ultra | Mega |\n| --- | --- | :---: | :---: | :---: | :---: |\n| 🧭 Car Reference Data | `listMakes`, `listModels`, `getUsedCarFilters`, `getNewCarFilters`, `listFinanceProviders`, `getFuelPrices` | ✓ | ✓ | ✓ | ✓ |\n| 🚗 Used Car Listings | `searchUsedCars`, `getUsedCarDetails`, `searchUsedCarsByUrl`, `getUsedCarDetailsByUrl` | ✓ | ✓ | ✓ | ✓ |\n| 🆕 New Car Catalogue | `searchNewCars`, `getNewCarDetails`, `searchNewCarsByUrl`, `getNewCarDetailsByUrl`, `getNewCarLineup`, `compareNewCars`, `getCompareSuggestions` | ✓ | ✓ | ✓ | ✓ |\n| 🔎 Marketplace Search Tools | `searchMotory`, `getSearchSuggestions`, `resolveUrl` | ✓ | ✓ | ✓ | ✓ |\n| 🏷️ Dealers and Offers | `listDealers`, `getDealerDetails`, `listCarOffers`, `getCarOfferDetails` | ✓ | ✗ | ✓ | ✓ |\n| 📰 Car News and Videos | `listNewsCategories`, `getNewsByCategory`, `searchNews`, `getNewsDetails`, `getNewsAuthorDetails`, `getNewsByAuthor`, `listNewsAuthorTags`, `getNewsByTag`, `listMostReadNews`, `listVideoCategories`, `listVideos`, `getVideoDetails` | ✓ | ✗ | ✓ | ✓ |\n| 🛠️ Automotive Business Directory | `searchDirectory`, `getDirectoryBusinessDetails`, `getDirectoryCompanyDetails`, `searchDirectoryCompanies`, `listDirectoryCompanyBranches`, `listDirectoryServices`, `listDirectoryAmenities`, `listDirectoryCities`, `listDirectoryMakes` | ✓ | ✗ | ✗ | ✓ |\n\n## Common Use Cases\n\n- Build used car listing and car price comparison apps for Saudi Arabia and Jordan.\n- Track used car asking prices by make, model, year, mileage and city for price research and valuation models.\n- Track new car prices by model year and grade, and compare the prices of the selling companies.\n- Compare car offers, financing deals and finance providers across brands.\n- Monitor dealer stock, showroom locations and contact numbers.\n- Build side-by-side new car comparison pages.\n- Build a Saudi automotive business directory of workshops, spare parts shops, car washes and showrooms with opening hours.\n- Power car news, car video and fuel price sections in English and Arabic.\n- Generate automotive leads from seller, dealer and selling company contacts.\n- Power pages that start from a pasted motory.com link.\n\n## Built for Developers\n\nEvery endpoint is a `GET` request with query parameters. Pick a market with `country` (`sa` or `jo`) and a language with `lang` (`en` or `ar`), then start with `listMakes`, `listModels` and the filter endpoints to get valid ids before you search. Lists take `page` and `page_size` and report `total_items` and `total_pages` where Motory provides them. Successful responses carry `success: true` and `data`; failures carry `success: false` and a message that explains what to change.\n\nEvery id a request takes is returned by another endpoint: `make_id` by `listMakes`, `model_id` by `listModels`, `vehicle_id` by the used and new car searches, `dealer_id` by `listDealers`, `offer_id` by `listCarOffers`, `finance_provider_id` by `listFinanceProviders`, directory ids by the directory vocabularies and searches, and `news_id`, `author_id`, `tag_id` and `video_id` by the news and video lists. Ids belong to one market, so use them with the same `country`. Field names and values are Motory's own, and every request and response is documented with examples in the endpoint reference.\n\n## Why Use This API?\n\n- Cover Motory with one integration: used cars, new cars, prices, financing, offers, dealers, comparisons, the Saudi business directory, news, videos and fuel prices.\n- Reach both markets, Saudi Arabia and Jordan, with the same endpoints.\n- Search like a Motory shopper, with 21 used car filters, filter options with live counts and 7 sort orders.\n- Reach the seller, dealer and selling company contacts behind every car.\n- Start from make and model ids, typed text or pasted motory.com links, in English or Arabic.\n\n## API Categories\n\n- Reference\n- Used Cars\n- New Cars\n- Search\n- Dealers\n- Offers\n- Directory\n- News\n- Videos\n\n## Start Building\n\nPick a market and a language, get make and model ids, search used cars, new cars and offers with the filters your users need, then open the listings, cars, dealers, offers, directory businesses, articles and videos your product requires. Start on Basic to try every endpoint, then choose Pro, Ultra or Mega according to the endpoints your production workflow needs.", "x-website": "https://motory.com", "x-public": true, "x-thumbnail": "https://rapidapi-prod-apis.s3.amazonaws.com/953f4cd1-733d-4957-85bc-7a2f811beef5.png", "x-version-lifecycle": "active", "termsOfService": "Unofficial Motory (motory.com) Saudi Arabia and Jordan car marketplace data API; not affiliated with Motory." }, "servers": [ { "url": "https://rapid-api-tools-worker.pictureperfect.workers.dev/happy-endpoint/api/tools/motory-api", "description": "Base URL" } ], "tags": [ { "name": "Reference", "description": "Reference", "index": 0 }, { "name": "Used Cars", "description": "Used Cars", "index": 1 }, { "name": "New Cars", "description": "New Cars", "index": 2 }, { "name": "Search", "description": "Search", "index": 3 }, { "name": "Dealers", "description": "Dealers", "index": 4 }, { "name": "Offers", "description": "Offers", "index": 5 }, { "name": "Directory", "description": "Directory", "index": 6 }, { "name": "News", "description": "News", "index": 7 }, { "name": "Videos", "description": "Videos", "index": 8 }, { "name": "Health", "description": "Health", "index": 9 } ], "components": { "schemas": { "CommonHealthCheckResponse": { "type": "object", "properties": { "success": { "type": "boolean", "example": true } }, "required": [ "success" ] }, "MotorySuccessResponseSchema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ], "example": true }, "data": { "nullable": true } }, "required": [ "success" ] }, "MotoryErrorResponseSchema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "example": false }, "message": { "type": "string", "example": "Invalid request parameters." } }, "required": [ "success", "message" ] } }, "parameters": {} }, "paths": { "/status": { "get": { "tags": [ "Health" ], "responses": { "200": { "description": "Health check", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommonHealthCheckResponse" } } } } } } }, "/makes": { "get": { "tags": [ "Reference" ], "operationId": "listMakes", "description": "List car makes with their ids and logos: the used-car makes that have cars for sale, or the full new-car brand catalogue. Each make id feeds /models, /used-cars, /new-cars and the filters; call it with the country you will search.", "parameters": [ { "schema": { "type": "string", "description": "**Which make list to return.** Required.\n\n- `used` — makes that currently have used cars for sale (the ids to send to `/used-cars`)\n- `new` — the full new-car brand catalogue (the ids to send to `/new-cars`)\n\nThe two lists overlap but differ: some makes appear only among used cars and some brands have no used listings. A make id is the same in both lists.", "enum": [ "used", "new" ], "example": "used" }, "required": true, "description": "**Which make list to return.** Required.\n\n- `used` — makes that currently have used cars for sale (the ids to send to `/used-cars`)\n- `new` — the full new-car brand catalogue (the ids to send to `/new-cars`)\n\nThe two lists overlap but differ: some makes appear only among used cars and some brands have no used listings. A make id is the same in both lists.", "name": "condition", "in": "query" }, { "schema": { "type": "string", "description": "**Market to read.** Optional; defaults to `sa`.\n\n- `sa` — Saudi Arabia (prices in SAR)\n- `jo` — Jordan (prices in JOD)\n\nEach market has its own inventory and its own ids (makes, models, cities, body types, dealers, vehicles). Send only ids from a call made with the same `country`. An id from the other market is answered as an unknown id:\n\n- **404** — a lookup by id: every details route, `/models`, `/finance-providers`, and `category_id` on `/category-news` and `/videos`.\n- **400 naming the param** — `make_id`, `model_id` and `finance_provider_id` on `/new-cars` and `/new-car-filters`; `make_id` and `city_id` on `/dealers`; `make_id` and `company_id` on `/offers`; `make_id`, `author_id` and `category_id` as filters of the news lists, and `make_id` on `/videos` (on `/tag-news`, an unknown `author_id` with a tag that is not a make returns an empty list when the tag has articles in the requested `lang`, and 404 otherwise).\n- **Empty result** — every other id filter, for example `body_type_id`, `fuel_type_id`, `transmission_id` or `origin_id` on `/new-cars`, every `/used-cars` and `/used-car-filters` filter, and `dealer_id` on `/dealers`.", "enum": [ "sa", "jo" ], "default": "sa" }, "required": false, "description": "**Market to read.** Optional; defaults to `sa`.\n\n- `sa` — Saudi Arabia (prices in SAR)\n- `jo` — Jordan (prices in JOD)\n\nEach market has its own inventory and its own ids (makes, models, cities, body types, dealers, vehicles). Send only ids from a call made with the same `country`. An id from the other market is answered as an unknown id:\n\n- **404** — a lookup by id: every details route, `/models`, `/finance-providers`, and `category_id` on `/category-news` and `/videos`.\n- **400 naming the param** — `make_id`, `model_id` and `finance_provider_id` on `/new-cars` and `/new-car-filters`; `make_id` and `city_id` on `/dealers`; `make_id` and `company_id` on `/offers`; `make_id`, `author_id` and `category_id` as filters of the news lists, and `make_id` on `/videos` (on `/tag-news`, an unknown `author_id` with a tag that is not a make returns an empty list when the tag has articles in the requested `lang`, and 404 otherwise).\n- **Empty result** — every other id filter, for example `body_type_id`, `fuel_type_id`, `transmission_id` or `origin_id` on `/new-cars`, every `/used-cars` and `/used-car-filters` filter, and `dealer_id` on `/dealers`.", "name": "country", "in": "query" }, { "schema": { "type": "string", "description": "**Response language.** Optional; defaults to `en`.\n\n- `en` — English\n- `ar` — Arabic\n\nChanges labels, titles and descriptions only; ids and numeric values are the same in both languages.", "enum": [ "en", "ar" ], "default": "en" }, "required": false, "description": "**Response language.** Optional; defaults to `en`.\n\n- `en` — English\n- `ar` — Arabic\n\nChanges labels, titles and descriptions only; ids and numeric values are the same in both languages.", "name": "lang", "in": "query" } ], "responses": { "200": { "description": "**Car makes with their ids and logos** — the `make_id` values every search, model list and filter endpoint takes.\n\n- `condition=used` — the makes that have used cars for sale.\n- `condition=new` — the whole new-car brand catalogue.\n\nRows are `{id, name, logo}` in the marketplace's own order. Ids are per market: Toyota in Saudi Arabia and Toyota in Jordan have different ids, so call this with the `country` you will search.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MotorySuccessResponseSchema" }, "example": { "success": true, "data": { "items": [ { "id": 90, "name": "Toyota", "logo": "https://s3.eu-central-1.amazonaws.com/v3-common.motory.com/taxonomy/l-1669878465.8496-638852c1cf6f3.webp" } ] } } } } }, "400": { "description": "Bad request — a parameter is missing, malformed or out of range", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MotoryErrorResponseSchema" } } } }, "404": { "description": "Not found — the requested id or link does not exist", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MotoryErrorResponseSchema" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MotoryErrorResponseSchema" } } } }, "503": { "description": "Service busy — retry shortly", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MotoryErrorResponseSchema" } } } } } } }, "/models": { "get": { "tags": [ "Reference" ], "operationId": "listModels", "description": "List one make's models with their ids, for used cars that are for sale or for the new-car model catalogue. Takes a make_id from /makes and a condition; the model id feeds /used-cars and /new-cars.", "parameters": [ { "schema": { "type": "integer", "description": "**Make id.** Required; for example `90` (Toyota in Saudi Arabia).\n\nTake `id` from `/makes` called with the same `country` and `condition`. An id unknown in the selected market returns 404; a real make with no models in the chosen list returns an empty `items` list.", "minimum": 1, "example": 90 }, "required": true, "description": "**Make id.** Required; for example `90` (Toyota in Saudi Arabia).\n\nTake `id` from `/makes` called with the same `country` and `condition`. An id unknown in the selected market returns 404; a real make with no models in the chosen list returns an empty `items` list.", "name": "make_id", "in": "query" }, { "schema": { "type": "string", "description": "**Which model list to return.** Required.\n\n- `used` — the make's models that currently have used cars for sale\n- `new` — the make's full new-car model catalogue, including models with no car currently listed\n\nA model id is the same in both lists.", "enum": [ "used", "new" ], "example": "used" }, "required": true, "description": "**Which model list to return.** Required.\n\n- `used` — the make's models that currently have used cars for sale\n- `new` — the make's full new-car model catalogue, including models with no car currently listed\n\nA model id is the same in both lists.", "name": "condition", "in": "query" }, { "schema": { "type": "string", "description": "**Market to read.** Optional; defaults to `sa`.\n\n- `sa` — Saudi Arabia (prices in SAR)\n- `jo` — Jordan (prices in JOD)\n\nEach market has its own inventory and its own ids (makes, models, cities, body types, dealers, vehicles). Send only ids from a call made with the same `country`. An id from the other market is answered as an unknown id:\n\n- **404** — a lookup by id: every details route, `/models`, `/finance-providers`, and `category_id` on `/category-news` and `/videos`.\n- **400 naming the param** — `make_id`, `model_id` and `finance_provider_id` on `/new-cars` and `/new-car-filters`; `make_id` and `city_id` on `/dealers`; `make_id` and `company_id` on `/offers`; `make_id`, `author_id` and `category_id` as filters of the news lists, and `make_id` on `/videos` (on `/tag-news`, an unknown `author_id` with a tag that is not a make returns an empty list when the tag has articles in the requested `lang`, and 404 otherwise).\n- **Empty result** — every other id filter, for example `body_type_id`, `fuel_type_id`, `transmission_id` or `origin_id` on `/new-cars`, every `/used-cars` and `/used-car-filters` filter, and `dealer_id` on `/dealers`.", "enum": [ "sa", "jo" ], "default": "sa" }, "required": false, "description": "**Market to read.** Optional; defaults to `sa`.\n\n- `sa` — Saudi Arabia (prices in SAR)\n- `jo` — Jordan (prices in JOD)\n\nEach market has its own inventory and its own ids (makes, models, cities, body types, dealers, vehicles). Send only ids from a call made with the same `country`. An id from the other market is answered as an unknown id:\n\n- **404** — a lookup by id: every details route, `/models`, `/finance-providers`, and `category_id` on `/category-news` and `/videos`.\n- **400 naming the param** — `make_id`, `model_id` and `finance_provider_id` on `/new-cars` and `/new-car-filters`; `make_id` and `city_id` on `/dealers`; `make_id` and `company_id` on `/offers`; `make_id`, `author_id` and `category_id` as filters of the news lists, and `make_id` on `/videos` (on `/tag-news`, an unknown `author_id` with a tag that is not a make returns an empty list when the tag has articles in the requested `lang`, and 404 otherwise).\n- **Empty result** — every other id filter, for example `body_type_id`, `fuel_type_id`, `transmission_id` or `origin_id` on `/new-cars`, every `/used-cars` and `/used-car-filters` filter, and `dealer_id` on `/dealers`.", "name": "country", "in": "query" }, { "schema": { "type": "string", "description": "**Response language.** Optional; defaults to `en`.\n\n- `en` — English\n- `ar` — Arabic\n\nChanges labels, titles and descriptions only; ids and numeric values are the same in both languages.", "enum": [ "en", "ar" ], "default": "en" }, "required": false, "description": "**Response language.** Optional; defaults to `en`.\n\n- `en` — English\n- `ar` — Arabic\n\nChanges labels, titles and descriptions only; ids and numeric values are the same in both languages.", "name": "lang", "in": "query" } ], "responses": { "200": { "description": "**One make's models with their ids** — the `model_id` values `/used-cars`, `/new-cars` and the filter endpoints take.\n\n- `condition=used` — the models that have used cars for sale.\n- `condition=new` — the make's whole new-car model catalogue.\n\nRows are `{id, name}`. For the current new-car line-up with price ranges and images, use `/new-car-lineup`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MotorySuccessResponseSchema" }, "example": { "success": true, "data": { "items": [ { "id": 406, "name": "Fortuner" } ] } } } } }, "400": { "description": "Bad request — a parameter is missing, malformed or out of range", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MotoryErrorResponseSchema" } } } }, "404": { "description": "Not found — the requested id or link does not exist", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MotoryErrorResponseSchema" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MotoryErrorResponseSchema" } } } }, "503": { "description": "Service busy — retry shortly", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MotoryErrorResponseSchema" } } } } } } }, "/new-car-lineup": { "get": { "tags": [ "Reference" ], "operationId": "getNewCarLineup", "description": "Show a make's current new-car line-up: one row per model with starting and top price, body type, model year and images, plus the make's selling companies, optionally narrowed to one or more body types. Takes a make_id from /makes (condition=new); follow a row's model_id into /new-cars.", "parameters": [ { "schema": { "type": "integer", "description": "**Make id.** Required; for example `90` (Toyota in Saudi Arabia).\n\nTake `id` from `/makes` (`condition=new`) called with the same `country`. An id unknown in the selected market returns 404; a make with no new cars currently sold returns empty lists.", "minimum": 1, "example": 90 }, "required": true, "description": "**Make id.** Required; for example `90` (Toyota in Saudi Arabia).\n\nTake `id` from `/makes` (`condition=new`) called with the same `country`. An id unknown in the selected market returns 404; a make with no new cars currently sold returns empty lists.", "name": "make_id", "in": "query" }, { "schema": { "type": "string", "description": "**Body type filter (SUV, Sedan, Hatchback…).** Optional; one or more body type ids, comma-separated; a model of any listed body type is kept.\n\nTake `value` from the `body_type_id` entry of `/new-car-filters` called with the same `country`. An id matching no model of the make gives empty `items`." }, "required": false, "description": "**Body type filter (SUV, Sedan, Hatchback…).** Optional; one or more body type ids, comma-separated; a model of any listed body type is kept.\n\nTake `value` from the `body_type_id` entry of `/new-car-filters` called with the same `country`. An id matching no model of the make gives empty `items`.", "name": "body_type_id", "in": "query" }, { "schema": { "type": "string", "description": "**Market to read.** Optional; defaults to `sa`.\n\n- `sa` — Saudi Arabia (prices in SAR)\n- `jo` — Jordan (prices in JOD)\n\nEach market has its own inventory and its own ids (makes, models, cities, body types, dealers, vehicles). Send only ids from a call made with the same `country`. An id from the other market is answered as an unknown id:\n\n- **404** — a lookup by id: every details route, `/models`, `/finance-providers`, and `category_id` on `/category-news` and `/videos`.\n- **400 naming the param** — `make_id`, `model_id` and `finance_provider_id` on `/new-cars` and `/new-car-filters`; `make_id` and `city_id` on `/dealers`; `make_id` and `company_id` on `/offers`; `make_id`, `author_id` and `category_id` as filters of the news lists, and `make_id` on `/videos` (on `/tag-news`, an unknown `author_id` with a tag that is not a make returns an empty list when the tag has articles in the requested `lang`, and 404 otherwise).\n- **Empty result** — every other id filter, for example `body_type_id`, `fuel_type_id`, `transmission_id` or `origin_id` on `/new-cars`, every `/used-cars` and `/used-car-filters` filter, and `dealer_id` on `/dealers`.", "enum": [ "sa", "jo" ], "default": "sa" }, "required": false, "description": "**Market to read.** Optional; defaults to `sa`.\n\n- `sa` — Saudi Arabia (prices in SAR)\n- `jo` — Jordan (prices in JOD)\n\nEach market has its own inventory and its own ids (makes, models, cities, body types, dealers, vehicles). Send only ids from a call made with the same `country`. An id from the other market is answered as an unknown id:\n\n- **404** — a lookup by id: every details route, `/models`, `/finance-providers`, and `category_id` on `/category-news` and `/videos`.\n- **400 naming the param** — `make_id`, `model_id` and `finance_provider_id` on `/new-cars` and `/new-car-filters`; `make_id` and `city_id` on `/dealers`; `make_id` and `company_id` on `/offers`; `make_id`, `author_id` and `category_id` as filters of the news lists, and `make_id` on `/videos` (on `/tag-news`, an unknown `author_id` with a tag that is not a make returns an empty list when the tag has articles in the requested `lang`, and 404 otherwise).\n- **Empty result** — every other id filter, for example `body_type_id`, `fuel_type_id`, `transmission_id` or `origin_id` on `/new-cars`, every `/used-cars` and `/used-car-filters` filter, and `dealer_id` on `/dealers`.", "name": "country", "in": "query" }, { "schema": { "type": "string", "description": "**Response language.** Optional; defaults to `en`.\n\n- `en` — English\n- `ar` — Arabic\n\nChanges labels, titles and descriptions only; ids and numeric values are the same in both languages.", "enum": [ "en", "ar" ], "default": "en" }, "required": false, "description": "**Response language.** Optional; defaults to `en`.\n\n- `en` — English\n- `ar` — Arabic\n\nChanges labels, titles and descriptions only; ids and numeric values are the same in both languages.", "name": "lang", "in": "query" } ], "responses": { "200": { "description": "**One make's current new-car line-up**: one row per model with its starting and top price, body type, model year and images, plus the make's selling `companies`.\n\n- Rows carry `make_id`/`model_id` for `/new-cars` (list the model's grades).\n- `min_price`/`max_price` are strings in the market currency; `max_price` can be null when only one price is published.\n- Only models currently sold are listed; `/models` with `condition=new` gives the make's whole model catalogue.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MotorySuccessResponseSchema" }, "example": { "success": true, "data": { "items": [ { "make_id": 90, "model_id": 2628, "body_type": "SUV", "min_monthly_installment": null, "make": "Toyota", "model": "Raize", "year": 2026, "min_price": "68827", "max_price": "75497", "icon": "https://s3.eu-central-1.amazonaws.com/v3-common.motory.com/taxonomy/l-1669878465.8496-638852c1cf6f3.webp", "image": "https://s3.eu-central-1.amazonaws.com/v3-ncg.motory.com/vehicle-new/l-1665387403.1176-6343cb8b1cb41.webp", "currency": "SR" } ], "companies": [ { "id": 1, "company_name": "Abdul Latif Jameel Motors - Toyota", "logo": "https://s3.eu-central-1.amazonaws.com/v3-companies.motory.com/company/l-1787489653.8728-6a8aed75d513a.webp", "description": "Contact the dealer's customer service for any inquiries or concerns you may have", "phone": "+9668004400055", "whatsapp": null } ] } } } } }, "400": { "description": "Bad request — a parameter is missing, malformed or out of range", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MotoryErrorResponseSchema" } } } }, "404": { "description": "Not found — the requested id or link does not exist", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MotoryErrorResponseSchema" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MotoryErrorResponseSchema" } } } }, "503": { "description": "Service busy — retry shortly", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MotoryErrorResponseSchema" } } } } } } }, "/used-car-filters": { "get": { "tags": [ "Reference" ], "operationId": "getUsedCarFilters", "description": "Get the used-car filter options (cities, makes, models, years, price bands, body, fuel, transmission, mileage, colour, origin, electric range, seller types and dealers) with result counts, narrowed by the /used-cars filters except keyword and pricing. Pass the option values back to /used-cars.", "parameters": [ { "schema": { "type": "string", "description": "**Market to read.** Optional; defaults to `sa`.\n\n- `sa` — Saudi Arabia (prices in SAR)\n- `jo` — Jordan (prices in JOD)\n\nEach market has its own inventory and its own ids (makes, models, cities, body types, dealers, vehicles). Send only ids from a call made with the same `country`. An id from the other market is answered as an unknown id:\n\n- **404** — a lookup by id: every details route, `/models`, `/finance-providers`, and `category_id` on `/category-news` and `/videos`.\n- **400 naming the param** — `make_id`, `model_id` and `finance_provider_id` on `/new-cars` and `/new-car-filters`; `make_id` and `city_id` on `/dealers`; `make_id` and `company_id` on `/offers`; `make_id`, `author_id` and `category_id` as filters of the news lists, and `make_id` on `/videos` (on `/tag-news`, an unknown `author_id` with a tag that is not a make returns an empty list when the tag has articles in the requested `lang`, and 404 otherwise).\n- **Empty result** — every other id filter, for example `body_type_id`, `fuel_type_id`, `transmission_id` or `origin_id` on `/new-cars`, every `/used-cars` and `/used-car-filters` filter, and `dealer_id` on `/dealers`.", "enum": [ "sa", "jo" ], "default": "sa" }, "required": false, "description": "**Market to read.** Optional; defaults to `sa`.\n\n- `sa` — Saudi Arabia (prices in SAR)\n- `jo` — Jordan (prices in JOD)\n\nEach market has its own inventory and its own ids (makes, models, cities, body types, dealers, vehicles). Send only ids from a call made with the same `country`. An id from the other market is answered as an unknown id:\n\n- **404** — a lookup by id: every details route, `/models`, `/finance-providers`, and `category_id` on `/category-news` and `/videos`.\n- **400 naming the param** — `make_id`, `model_id` and `finance_provider_id` on `/new-cars` and `/new-car-filters`; `make_id` and `city_id` on `/dealers`; `make_id` and `company_id` on `/offers`; `make_id`, `author_id` and `category_id` as filters of the news lists, and `make_id` on `/videos` (on `/tag-news`, an unknown `author_id` with a tag that is not a make returns an empty list when the tag has articles in the requested `lang`, and 404 otherwise).\n- **Empty result** — every other id filter, for example `body_type_id`, `fuel_type_id`, `transmission_id` or `origin_id` on `/new-cars`, every `/used-cars` and `/used-car-filters` filter, and `dealer_id` on `/dealers`.", "name": "country", "in": "query" }, { "schema": { "type": "string", "description": "**Response language.** Optional; defaults to `en`.\n\n- `en` — English\n- `ar` — Arabic\n\nChanges labels, titles and descriptions only; ids and numeric values are the same in both languages.", "enum": [ "en", "ar" ], "default": "en" }, "required": false, "description": "**Response language.** Optional; defaults to `en`.\n\n- `en` — English\n- `ar` — Arabic\n\nChanges labels, titles and descriptions only; ids and numeric values are the same in both languages.", "name": "lang", "in": "query" }, { "schema": { "type": "string", "description": "**Make filter.** Optional; one or more make ids, comma-separated (for example `90,71`). A car matching any listed make is kept.\n\nTake ids from `/makes` called with the same `country`." }, "required": false, "description": "**Make filter.** Optional; one or more make ids, comma-separated (for example `90,71`). A car matching any listed make is kept.\n\nTake ids from `/makes` called with the same `country`.", "name": "make_id", "in": "query" }, { "schema": { "type": "string", "description": "**Model filter.** Optional; one or more model ids, comma-separated. A car matching any listed model is kept.\n\nTake ids from `/models`. Works without `make_id`; combined with it, only the listed models are kept (a make with none of its models listed drops out)." }, "required": false, "description": "**Model filter.** Optional; one or more model ids, comma-separated. A car matching any listed model is kept.\n\nTake ids from `/models`. Works without `make_id`; combined with it, only the listed models are kept (a make with none of its models listed drops out).", "name": "model_id", "in": "query" }, { "schema": { "type": "string", "description": "**City filter.** Optional; one or more ids, comma-separated; any listed value matches.\n\nTake ids from `/used-car-filters` (cities) called with the same `country`." }, "required": false, "description": "**City filter.** Optional; one or more ids, comma-separated; any listed value matches.\n\nTake ids from `/used-car-filters` (cities) called with the same `country`.", "name": "city_id", "in": "query" }, { "schema": { "type": "integer", "description": "**Earliest model year.** Optional; for example `2020`.\n\nCombine with `max_year` for a range (equal values select one year). `min_year` greater than `max_year` is rejected with 400.", "minimum": 1900, "maximum": 2100 }, "required": false, "description": "**Earliest model year.** Optional; for example `2020`.\n\nCombine with `max_year` for a range (equal values select one year). `min_year` greater than `max_year` is rejected with 400.", "name": "min_year", "in": "query" }, { "schema": { "type": "integer", "description": "**Latest model year.** Optional; for example `2024`.\n\nCombine with `min_year` for a range. `max_year` lower than `min_year` is rejected with 400.", "minimum": 1900, "maximum": 2100 }, "required": false, "description": "**Latest model year.** Optional; for example `2024`.\n\nCombine with `min_year` for a range. `max_year` lower than `min_year` is rejected with 400.", "name": "max_year", "in": "query" }, { "schema": { "type": "integer", "description": "**Minimum asking price**, whole number in the market currency (SAR for `sa`, JOD for `jo`). Optional.\n\nAny price bound keeps only listings that show a price — listings whose price reads \"Contact Seller\" are excluded. `min_price` greater than `max_price` is rejected with 400.", "minimum": 0, "maximum": 100000000 }, "required": false, "description": "**Minimum asking price**, whole number in the market currency (SAR for `sa`, JOD for `jo`). Optional.\n\nAny price bound keeps only listings that show a price — listings whose price reads \"Contact Seller\" are excluded. `min_price` greater than `max_price` is rejected with 400.", "name": "min_price", "in": "query" }, { "schema": { "type": "integer", "description": "**Maximum asking price**, whole number in the market currency (SAR for `sa`, JOD for `jo`). Optional.\n\nAny price bound keeps only listings that show a price. Send `max_price` alone for \"up to\", both bounds for a band.", "minimum": 1, "maximum": 100000000 }, "required": false, "description": "**Maximum asking price**, whole number in the market currency (SAR for `sa`, JOD for `jo`). Optional.\n\nAny price bound keeps only listings that show a price. Send `max_price` alone for \"up to\", both bounds for a band.", "name": "max_price", "in": "query" }, { "schema": { "type": "string", "description": "**Body type filter (SUV, Sedan, Hatchback…).** Optional; one or more ids, comma-separated; any listed value matches.\n\nTake ids from `/used-car-filters` (body types) called with the same `country`." }, "required": false, "description": "**Body type filter (SUV, Sedan, Hatchback…).** Optional; one or more ids, comma-separated; any listed value matches.\n\nTake ids from `/used-car-filters` (body types) called with the same `country`.", "name": "body_type_id", "in": "query" }, { "schema": { "type": "string", "description": "**Fuel type filter (Gasoline, Hybrid, Electric, Diesel…).** Optional; one or more ids, comma-separated; any listed value matches.\n\nTake ids from `/used-car-filters` (fuel types) called with the same `country`." }, "required": false, "description": "**Fuel type filter (Gasoline, Hybrid, Electric, Diesel…).** Optional; one or more ids, comma-separated; any listed value matches.\n\nTake ids from `/used-car-filters` (fuel types) called with the same `country`.", "name": "fuel_type_id", "in": "query" }, { "schema": { "type": "string", "description": "**Transmission filter (Automatic, Manual, CVT…).** Optional; one or more ids, comma-separated; any listed value matches.\n\nTake ids from `/used-car-filters` (transmissions) called with the same `country`." }, "required": false, "description": "**Transmission filter (Automatic, Manual, CVT…).** Optional; one or more ids, comma-separated; any listed value matches.\n\nTake ids from `/used-car-filters` (transmissions) called with the same `country`.", "name": "transmission_id", "in": "query" }, { "schema": { "type": "string", "description": "**Mileage band filter (for example \"0 km\", \"10,000-19,999 km\", \"200,000+ km\").** Optional; one or more ids, comma-separated; any listed value matches.\n\nTake ids from `/used-car-filters` (mileage bands) called with the same `country`." }, "required": false, "description": "**Mileage band filter (for example \"0 km\", \"10,000-19,999 km\", \"200,000+ km\").** Optional; one or more ids, comma-separated; any listed value matches.\n\nTake ids from `/used-car-filters` (mileage bands) called with the same `country`.", "name": "mileage_id", "in": "query" }, { "schema": { "type": "string", "description": "**Exterior colour filter.** Optional; one or more ids, comma-separated; any listed value matches.\n\nTake ids from `/used-car-filters` (colours) called with the same `country`." }, "required": false, "description": "**Exterior colour filter.** Optional; one or more ids, comma-separated; any listed value matches.\n\nTake ids from `/used-car-filters` (colours) called with the same `country`.", "name": "color_id", "in": "query" }, { "schema": { "type": "string", "description": "**Manufacturer origin filter (Chinese, Japanese, German, Korean, American…).** Optional; one or more ids, comma-separated; any listed value matches.\n\nTake ids from `/used-car-filters` (origins) called with the same `country`." }, "required": false, "description": "**Manufacturer origin filter (Chinese, Japanese, German, Korean, American…).** Optional; one or more ids, comma-separated; any listed value matches.\n\nTake ids from `/used-car-filters` (origins) called with the same `country`.", "name": "origin_id", "in": "query" }, { "schema": { "type": "boolean", "description": "**Only cars offered with financing.** Optional.\n\n- `true` — keep only listings with financing available\n- omitted — all listings\n\n`false` is rejected with 400: there is no \"without financing\" filter.\n\nIn a market whose used listings carry no financing, `has_financing=true` returns `total: 0` and zero counts.", "example": "" }, "required": false, "description": "**Only cars offered with financing.** Optional.\n\n- `true` — keep only listings with financing available\n- omitted — all listings\n\n`false` is rejected with 400: there is no \"without financing\" filter.\n\nIn a market whose used listings carry no financing, `has_financing=true` returns `total: 0` and zero counts.", "name": "has_financing", "in": "query" }, { "schema": { "type": "boolean", "description": "**Only cars that show a price.** Optional.\n\n- `true` — drop listings whose price reads \"Contact Seller\"\n- omitted — all listings\n\n`false` is rejected with 400.", "example": "" }, "required": false, "description": "**Only cars that show a price.** Optional.\n\n- `true` — drop listings whose price reads \"Contact Seller\"\n- omitted — all listings\n\n`false` is rejected with 400.", "name": "with_price_only", "in": "query" }, { "schema": { "type": "string", "description": "**Seller type.** Optional; omitted returns both.\n\n- `dealer` — dealerships and showrooms\n- `individual` — private sellers", "enum": [ "dealer", "individual" ] }, "required": false, "description": "**Seller type.** Optional; omitted returns both.\n\n- `dealer` — dealerships and showrooms\n- `individual` — private sellers", "name": "seller_type", "in": "query" }, { "schema": { "type": "string", "description": "**Dealers' stock only.** Optional; one or more dealer ids, comma-separated (for example `283165,496563`). A car listed by any of them is kept.\n\nTake `dealer_id` from `/dealers`, `seller_id` from a `/used-cars` row, or a `dealer` option of `/used-car-filters`. This is a dealer's whole stock, including zero-mileage cars; `/new-cars` has no dealer filter." }, "required": false, "description": "**Dealers' stock only.** Optional; one or more dealer ids, comma-separated (for example `283165,496563`). A car listed by any of them is kept.\n\nTake `dealer_id` from `/dealers`, `seller_id` from a `/used-cars` row, or a `dealer` option of `/used-car-filters`. This is a dealer's whole stock, including zero-mileage cars; `/new-cars` has no dealer filter.", "name": "dealer_id", "in": "query" }, { "schema": { "type": "integer", "description": "**Minimum electric range**, whole kilometres per full charge. Optional.\n\n- Any bound keeps only cars with a published electric range (electric cars, plug-in and range-extender hybrids).\n- Both bounds are inclusive.\n- The bounds narrow `total` and every option count except the fuel type counts, which ignore them.\n- `min_electric_range` greater than `max_electric_range` is rejected with 400.", "minimum": 0, "maximum": 10000 }, "required": false, "description": "**Minimum electric range**, whole kilometres per full charge. Optional.\n\n- Any bound keeps only cars with a published electric range (electric cars, plug-in and range-extender hybrids).\n- Both bounds are inclusive.\n- The bounds narrow `total` and every option count except the fuel type counts, which ignore them.\n- `min_electric_range` greater than `max_electric_range` is rejected with 400.", "name": "min_electric_range", "in": "query" }, { "schema": { "type": "integer", "description": "**Maximum electric range**, whole kilometres per full charge. Optional.\n\n- Any bound keeps only cars with a published electric range (electric cars, plug-in and range-extender hybrids).\n- Both bounds are inclusive.\n- The bounds narrow `total` and every option count except the fuel type counts, which ignore them.\n- Send `max_electric_range` alone for \"up to\", both bounds for a band.", "minimum": 1, "maximum": 10000 }, "required": false, "description": "**Maximum electric range**, whole kilometres per full charge. Optional.\n\n- Any bound keeps only cars with a published electric range (electric cars, plug-in and range-extender hybrids).\n- Both bounds are inclusive.\n- The bounds narrow `total` and every option count except the fuel type counts, which ignore them.\n- Send `max_electric_range` alone for \"up to\", both bounds for a band.", "name": "max_electric_range", "in": "query" } ], "responses": { "200": { "description": "**Used-car filter options with live result counts**, narrowed by the `/used-cars` filters you pass.\n\nOptions cover cities, makes, models, years, price bands, body types, fuel types, transmissions, mileage bands, colours, origins, seller types and dealers. `keyword` and `pricing` are rejected here with 400; send `has_financing=true` for the financing collection.\n\nResponse:\n\n- `total` — the number of used cars matching the filters sent (the figure `/used-cars` reports as `pagination.total_items`).\n- `filters[]` — one entry per filter: `field`, `label`, `type`, `is_multiple` and its options (`value`, `text`, `text_en`/`text_ar`, slugs, `count`; make and model options also carry the public listing `link`). Booleans carry their `count` directly.\n- Counts of a filter ignore that filter's own selection, so they show what each option would give. The fuel type counts also ignore `min_electric_range`/`max_electric_range`, which narrow `total` and every other count.\n- `value: \"-1\"` (`text` \"All\") — the \"All\" entry that some option lists start with (for example make, year and city), as the site shows it. Its `count` is the result with that filter left out. To get all values, omit the filter: `-1` is not a filter value and is rejected with 400.\n- `monthly_payment` — the site's monthly-payment group, present when `has_financing=true` is sent (the `has_financing` entry names it in `reset_field`). Its band from 0 counts the same cars as `has_financing=true`. No list route takes it.\n\nSending an option to `/used-cars` — the option `value` goes under its `field` name, except:\n\n- `year` → `min_year`/`max_year`.\n- `price_range` (`\"lo-hi\"`, `0` = no ceiling) → `min_price`/`max_price`.\n- `dealer` → `dealer_id`.\n- `seller_type` `1` → `dealer`, `0` → `individual`.\n- `electric_range` (`\"lo-hi\"` km, `0` = no ceiling; listed when `fuel_type_id` is the Electric fuel type alone) → `min_electric_range`/`max_electric_range`.\n\nPer market:\n\n- The model list appears once `make_id` is set.\n- Saudi Arabia lists cities and the seller types; its `dealer` options appear once `seller_type=dealer` is sent.\n- Jordan lists dealers instead of cities.\n- In a market whose used listings carry no financing, `has_financing=true` returns `total: 0`, zero counts and no option lists.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MotorySuccessResponseSchema" }, "example": { "success": true, "data": { "total": 1393, "filters": [ { "type": "radio", "field": "make_id", "search": true, "is_multiple": false, "label": "Make", "selected_values": [], "has_selected_values": false, "data": [ { "text": "All", "value": "-1", "count": 1393 }, { "text": "Toyota", "text_ar": "تويوتا", "text_en": "Toyota", "value": "90", "slug_ar": "تويوتا", "slug_en": "toyota", "count": 253, "selected": false, "reset_field": "model_id", "image": "https://s3.eu-central-1.amazonaws.com/v3-common.motory.com/taxonomy/l-1669878465.8496-638852c1cf6f3.webp", "link": "https://ksa.motory.com/en/cars-for-sale/toyota/" } ] }, { "type": "radio", "field": "year", "search": true, "search_limit": 11, "is_multiple": false, "label": "Year", "selected_values": [], "has_selected_values": false, "data": [ { "text": "All", "value": "-1", "count": 1393 }, { "text": "2027", "value": "2027", "count": 20, "selected": false, "reset_field": null, "link": null } ] }, { "field": "has_financing", "type": "boolean", "label": "Finance Available", "selected": false, "count": 863, "reset_field": "monthly_payment" }, { "field": "seller_type", "is_multiple": true, "type": "check_box", "label": "Seller type", "selected_values": [], "has_selected_values": false, "data": [ { "text": "Dealer", "value": "1", "count": 964, "selected": false, "reset_field": "dealer" } ] } ] } } } } }, "400": { "description": "Bad request — a parameter is missing, malformed or out of range", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MotoryErrorResponseSchema" } } } }, "404": { "description": "Not found — the requested id or link does not exist", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MotoryErrorResponseSchema" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MotoryErrorResponseSchema" } } } }, "503": { "description": "Service busy — retry shortly", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MotoryErrorResponseSchema" } } } } } } }, "/new-car-filters": { "get": { "tags": [ "Reference" ], "operationId": "getNewCarFilters", "description": "Get the new-car filter options (makes, models, model years, price bands, body, fuel, transmission, origin and electric range) with result counts, narrowed by the /new-cars filters except finance_provider_id. Pass the option values back to /new-cars.", "parameters": [ { "schema": { "type": "string", "description": "**Market to read.** Optional; defaults to `sa`.\n\n- `sa` — Saudi Arabia (prices in SAR)\n- `jo` — Jordan (prices in JOD)\n\nEach market has its own inventory and its own ids (makes, models, cities, body types, dealers, vehicles). Send only ids from a call made with the same `country`. An id from the other market is answered as an unknown id:\n\n- **404** — a lookup by id: every details route, `/models`, `/finance-providers`, and `category_id` on `/category-news` and `/videos`.\n- **400 naming the param** — `make_id`, `model_id` and `finance_provider_id` on `/new-cars` and `/new-car-filters`; `make_id` and `city_id` on `/dealers`; `make_id` and `company_id` on `/offers`; `make_id`, `author_id` and `category_id` as filters of the news lists, and `make_id` on `/videos` (on `/tag-news`, an unknown `author_id` with a tag that is not a make returns an empty list when the tag has articles in the requested `lang`, and 404 otherwise).\n- **Empty result** — every other id filter, for example `body_type_id`, `fuel_type_id`, `transmission_id` or `origin_id` on `/new-cars`, every `/used-cars` and `/used-car-filters` filter, and `dealer_id` on `/dealers`.", "enum": [ "sa", "jo" ], "default": "sa" }, "required": false, "description": "**Market to read.** Optional; defaults to `sa`.\n\n- `sa` — Saudi Arabia (prices in SAR)\n- `jo` — Jordan (prices in JOD)\n\nEach market has its own inventory and its own ids (makes, models, cities, body types, dealers, vehicles). Send only ids from a call made with the same `country`. An id from the other market is answered as an unknown id:\n\n- **404** — a lookup by id: every details route, `/models`, `/finance-providers`, and `category_id` on `/category-news` and `/videos`.\n- **400 naming the param** — `make_id`, `model_id` and `finance_provider_id` on `/new-cars` and `/new-car-filters`; `make_id` and `city_id` on `/dealers`; `make_id` and `company_id` on `/offers`; `make_id`, `author_id` and `category_id` as filters of the news lists, and `make_id` on `/videos` (on `/tag-news`, an unknown `author_id` with a tag that is not a make returns an empty list when the tag has articles in the requested `lang`, and 404 otherwise).\n- **Empty result** — every other id filter, for example `body_type_id`, `fuel_type_id`, `transmission_id` or `origin_id` on `/new-cars`, every `/used-cars` and `/used-car-filters` filter, and `dealer_id` on `/dealers`.", "name": "country", "in": "query" }, { "schema": { "type": "string", "description": "**Response language.** Optional; defaults to `en`.\n\n- `en` — English\n- `ar` — Arabic\n\nChanges labels, titles and descriptions only; ids and numeric values are the same in both languages.", "enum": [ "en", "ar" ], "default": "en" }, "required": false, "description": "**Response language.** Optional; defaults to `en`.\n\n- `en` — English\n- `ar` — Arabic\n\nChanges labels, titles and descriptions only; ids and numeric values are the same in both languages.", "name": "lang", "in": "query" }, { "schema": { "type": "integer", "description": "**Make filter.** Optional; one make id (for example `90`).\n\nTake ids from `/makes` called with the same `country`. One value only — a comma-separated list is rejected with 400.", "minimum": 1 }, "required": false, "description": "**Make filter.** Optional; one make id (for example `90`).\n\nTake ids from `/makes` called with the same `country`. One value only — a comma-separated list is rejected with 400.", "name": "make_id", "in": "query" }, { "schema": { "type": "integer", "description": "**Model filter.** Optional; one model id.\n\nTake ids from `/models`. Works without `make_id`. One value only — a comma-separated list is rejected with 400.", "minimum": 1 }, "required": false, "description": "**Model filter.** Optional; one model id.\n\nTake ids from `/models`. Works without `make_id`. One value only — a comma-separated list is rejected with 400.", "name": "model_id", "in": "query" }, { "schema": { "type": "integer", "description": "**Earliest model year.** Optional; for example `2025`.\n\nCombine with `max_year` for a range (equal values select one year). `min_year` greater than `max_year` is rejected with 400.\n\nCounts cover cars currently sold only. Archived model years, which `/new-cars` lists when nothing currently sold matches, are not counted here: a year range that holds only archived cars gives `total: 0`.", "minimum": 1900, "maximum": 2100 }, "required": false, "description": "**Earliest model year.** Optional; for example `2025`.\n\nCombine with `max_year` for a range (equal values select one year). `min_year` greater than `max_year` is rejected with 400.\n\nCounts cover cars currently sold only. Archived model years, which `/new-cars` lists when nothing currently sold matches, are not counted here: a year range that holds only archived cars gives `total: 0`.", "name": "min_year", "in": "query" }, { "schema": { "type": "integer", "description": "**Latest model year.** Optional; for example `2026`.\n\nCombine with `min_year` for a range. `max_year` lower than `min_year` is rejected with 400.\n\nCounts cover cars currently sold only. Archived model years, which `/new-cars` lists when nothing currently sold matches, are not counted here: a year range that holds only archived cars gives `total: 0`.", "minimum": 1900, "maximum": 2100 }, "required": false, "description": "**Latest model year.** Optional; for example `2026`.\n\nCombine with `min_year` for a range. `max_year` lower than `min_year` is rejected with 400.\n\nCounts cover cars currently sold only. Archived model years, which `/new-cars` lists when nothing currently sold matches, are not counted here: a year range that holds only archived cars gives `total: 0`.", "name": "max_year", "in": "query" }, { "schema": { "type": "integer", "description": "**Minimum price**, whole number in the market currency (SAR for `sa`, JOD for `jo`). Optional.\n\n`min_price` greater than `max_price` is rejected with 400.", "minimum": 0, "maximum": 100000000 }, "required": false, "description": "**Minimum price**, whole number in the market currency (SAR for `sa`, JOD for `jo`). Optional.\n\n`min_price` greater than `max_price` is rejected with 400.", "name": "min_price", "in": "query" }, { "schema": { "type": "integer", "description": "**Maximum price**, whole number in the market currency (SAR for `sa`, JOD for `jo`). Optional.\n\nSend `max_price` alone for \"up to\", both bounds for a band.", "minimum": 1, "maximum": 100000000 }, "required": false, "description": "**Maximum price**, whole number in the market currency (SAR for `sa`, JOD for `jo`). Optional.\n\nSend `max_price` alone for \"up to\", both bounds for a band.", "name": "max_price", "in": "query" }, { "schema": { "type": "string", "description": "**Body type filter (SUV, Sedan, Hatchback…).** Optional; one or more ids, comma-separated; any listed value matches.\n\nTake ids from `/new-car-filters` (body types) called with the same `country`." }, "required": false, "description": "**Body type filter (SUV, Sedan, Hatchback…).** Optional; one or more ids, comma-separated; any listed value matches.\n\nTake ids from `/new-car-filters` (body types) called with the same `country`.", "name": "body_type_id", "in": "query" }, { "schema": { "type": "string", "description": "**Fuel type filter (Gasoline, Hybrid, Plug-in Hybrid, Electric…).** Optional; one or more ids, comma-separated; any listed value matches.\n\nTake ids from `/new-car-filters` (fuel types) called with the same `country`." }, "required": false, "description": "**Fuel type filter (Gasoline, Hybrid, Plug-in Hybrid, Electric…).** Optional; one or more ids, comma-separated; any listed value matches.\n\nTake ids from `/new-car-filters` (fuel types) called with the same `country`.", "name": "fuel_type_id", "in": "query" }, { "schema": { "type": "string", "description": "**Transmission filter (Automatic, Manual, CVT…).** Optional; one or more ids, comma-separated; any listed value matches.\n\nTake ids from `/new-car-filters` (transmissions) called with the same `country`." }, "required": false, "description": "**Transmission filter (Automatic, Manual, CVT…).** Optional; one or more ids, comma-separated; any listed value matches.\n\nTake ids from `/new-car-filters` (transmissions) called with the same `country`.", "name": "transmission_id", "in": "query" }, { "schema": { "type": "string", "description": "**Manufacturer origin filter (Chinese, Japanese, German, Korean, American…).** Optional; one or more ids, comma-separated; any listed value matches.\n\nTake ids from `/new-car-filters` (origins) called with the same `country`." }, "required": false, "description": "**Manufacturer origin filter (Chinese, Japanese, German, Korean, American…).** Optional; one or more ids, comma-separated; any listed value matches.\n\nTake ids from `/new-car-filters` (origins) called with the same `country`.", "name": "origin_id", "in": "query" }, { "schema": { "type": "boolean", "description": "**Only cars offered with financing.** Optional.\n\n- `true` — keep only cars with financing available\n- omitted — all cars\n\n`false` is rejected with 400: there is no \"without financing\" filter.", "example": "" }, "required": false, "description": "**Only cars offered with financing.** Optional.\n\n- `true` — keep only cars with financing available\n- omitted — all cars\n\n`false` is rejected with 400: there is no \"without financing\" filter.", "name": "has_financing", "in": "query" }, { "schema": { "type": "integer", "description": "**Minimum electric range**, whole kilometres per full charge. Optional.\n\n- Any bound keeps only cars with a published electric range (electric cars, plug-in and range-extender hybrids).\n- Both bounds are inclusive.\n- The bounds narrow `total` and every option count except the fuel type counts, which ignore them.\n- `min_electric_range` greater than `max_electric_range` is rejected with 400.", "minimum": 0, "maximum": 10000 }, "required": false, "description": "**Minimum electric range**, whole kilometres per full charge. Optional.\n\n- Any bound keeps only cars with a published electric range (electric cars, plug-in and range-extender hybrids).\n- Both bounds are inclusive.\n- The bounds narrow `total` and every option count except the fuel type counts, which ignore them.\n- `min_electric_range` greater than `max_electric_range` is rejected with 400.", "name": "min_electric_range", "in": "query" }, { "schema": { "type": "integer", "description": "**Maximum electric range**, whole kilometres per full charge. Optional.\n\n- Any bound keeps only cars with a published electric range (electric cars, plug-in and range-extender hybrids).\n- Both bounds are inclusive.\n- The bounds narrow `total` and every option count except the fuel type counts, which ignore them.\n- Send `max_electric_range` alone for \"up to\", both bounds for a band.", "minimum": 1, "maximum": 10000 }, "required": false, "description": "**Maximum electric range**, whole kilometres per full charge. Optional.\n\n- Any bound keeps only cars with a published electric range (electric cars, plug-in and range-extender hybrids).\n- Both bounds are inclusive.\n- The bounds narrow `total` and every option count except the fuel type counts, which ignore them.\n- Send `max_electric_range` alone for \"up to\", both bounds for a band.", "name": "max_electric_range", "in": "query" } ], "responses": { "200": { "description": "**New-car filter options with live result counts**, narrowed by the `/new-cars` filters you pass.\n\nOptions cover makes, models, model years, price bands, body types, fuel types, transmissions and origins. `finance_provider_id` is rejected here with 400; finance providers are listed by `/finance-providers`.\n\nResponse:\n\n- `total` — the number of new cars currently sold that match the filters sent (the figure `/new-cars` reports as `pagination.total_items`). Archived model years, which `/new-cars` lists only when nothing currently sold matches, are not counted here.\n- `filters[]` — one entry per filter: `field`, `label`, `type`, `is_multiple` and its options (`value`, `text`, `text_en`/`text_ar`, slugs, `count`; make and model options also carry the public listing `link`). Booleans carry their `count` directly.\n- Counts of a filter ignore that filter's own selection. The fuel type counts also ignore `min_electric_range`/`max_electric_range`, which narrow `total` and every other count.\n- `value: \"-1\"` (`text` \"All\") — the \"All\" entry that some option lists start with (for example make and year), as the site shows it. Its `count` is the result with that filter left out. To get all values, omit the filter: `-1` is not a filter value and is rejected with 400.\n- `monthly_payment` — the site's monthly-payment group, present when `has_financing=true` is sent. Its band from 0 counts the same cars as `has_financing=true`. No list route takes it.\n\nSending an option to `/new-cars` — the option `value` goes under its `field` name, except:\n\n- `year` → `min_year`/`max_year`.\n- `price_range` (`\"lo-hi\"`, `0` = no ceiling) → `min_price`/`max_price`.\n- `electric_range` (`\"lo-hi\"` km, `0` = no ceiling; listed when `fuel_type_id` is the Electric fuel type alone) → `min_electric_range`/`max_electric_range`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MotorySuccessResponseSchema" }, "example": { "success": true, "data": { "total": 1239, "filters": [ { "type": "radio", "field": "make_id", "search": true, "is_multiple": false, "label": "Make", "selected_values": [], "has_selected_values": false, "data": [ { "text": "All", "value": "-1", "count": 1239 }, { "text": "Toyota", "text_ar": "تويوتا", "text_en": "Toyota", "value": "90", "slug_ar": "تويوتا", "slug_en": "toyota", "count": 129, "selected": false, "reset_field": "model_id", "image": "https://s3.eu-central-1.amazonaws.com/v3-common.motory.com/taxonomy/l-1669878465.8496-638852c1cf6f3.webp", "link": "https://ksa.motory.com/en/new-cars/toyota/" } ] }, { "type": "radio", "field": "year", "search": false, "search_limit": 11, "is_multiple": false, "label": "Year", "selected_values": [], "has_selected_values": false, "data": [ { "text": "All", "value": "-1", "count": 1239 }, { "text": "2027", "value": "2027", "count": 45, "selected": false, "reset_field": null, "link": null } ] }, { "field": "has_financing", "type": "boolean", "label": "Finance Available", "selected": false, "count": 748, "reset_field": "monthly_payment" } ] } } } } }, "400": { "description": "Bad request — a parameter is missing, malformed or out of range", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MotoryErrorResponseSchema" } } } }, "404": { "description": "Not found — the requested id or link does not exist", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MotoryErrorResponseSchema" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MotoryErrorResponseSchema" } } } }, "503": { "description": "Service busy — retry shortly", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MotoryErrorResponseSchema" } } } } } } }, "/finance-providers": { "get": { "tags": [ "Reference" ], "operationId": "listFinanceProviders", "description": "List the finance providers that finance new cars, optionally for one make. Takes an optional make_id from /makes (condition=new); a provider id is the finance_provider_id that /new-cars filters by.", "parameters": [ { "schema": { "type": "integer", "description": "**Only providers financing this make.** Optional; one make id.\n\nTake `id` from `/makes` (`condition=new`) called with the same `country`. An id unknown in the selected market returns 404; a real make no provider finances returns an empty `items` list.", "minimum": 1 }, "required": false, "description": "**Only providers financing this make.** Optional; one make id.\n\nTake `id` from `/makes` (`condition=new`) called with the same `country`. An id unknown in the selected market returns 404; a real make no provider finances returns an empty `items` list.", "name": "make_id", "in": "query" }, { "schema": { "type": "string", "description": "**Market to read.** Optional; defaults to `sa`.\n\n- `sa` — Saudi Arabia (prices in SAR)\n- `jo` — Jordan (prices in JOD)\n\nEach market has its own inventory and its own ids (makes, models, cities, body types, dealers, vehicles). Send only ids from a call made with the same `country`. An id from the other market is answered as an unknown id:\n\n- **404** — a lookup by id: every details route, `/models`, `/finance-providers`, and `category_id` on `/category-news` and `/videos`.\n- **400 naming the param** — `make_id`, `model_id` and `finance_provider_id` on `/new-cars` and `/new-car-filters`; `make_id` and `city_id` on `/dealers`; `make_id` and `company_id` on `/offers`; `make_id`, `author_id` and `category_id` as filters of the news lists, and `make_id` on `/videos` (on `/tag-news`, an unknown `author_id` with a tag that is not a make returns an empty list when the tag has articles in the requested `lang`, and 404 otherwise).\n- **Empty result** — every other id filter, for example `body_type_id`, `fuel_type_id`, `transmission_id` or `origin_id` on `/new-cars`, every `/used-cars` and `/used-car-filters` filter, and `dealer_id` on `/dealers`.", "enum": [ "sa", "jo" ], "default": "sa" }, "required": false, "description": "**Market to read.** Optional; defaults to `sa`.\n\n- `sa` — Saudi Arabia (prices in SAR)\n- `jo` — Jordan (prices in JOD)\n\nEach market has its own inventory and its own ids (makes, models, cities, body types, dealers, vehicles). Send only ids from a call made with the same `country`. An id from the other market is answered as an unknown id:\n\n- **404** — a lookup by id: every details route, `/models`, `/finance-providers`, and `category_id` on `/category-news` and `/videos`.\n- **400 naming the param** — `make_id`, `model_id` and `finance_provider_id` on `/new-cars` and `/new-car-filters`; `make_id` and `city_id` on `/dealers`; `make_id` and `company_id` on `/offers`; `make_id`, `author_id` and `category_id` as filters of the news lists, and `make_id` on `/videos` (on `/tag-news`, an unknown `author_id` with a tag that is not a make returns an empty list when the tag has articles in the requested `lang`, and 404 otherwise).\n- **Empty result** — every other id filter, for example `body_type_id`, `fuel_type_id`, `transmission_id` or `origin_id` on `/new-cars`, every `/used-cars` and `/used-car-filters` filter, and `dealer_id` on `/dealers`.", "name": "country", "in": "query" }, { "schema": { "type": "string", "description": "**Response language.** Optional; defaults to `en`.\n\n- `en` — English\n- `ar` — Arabic\n\nChanges labels, titles and descriptions only; ids and numeric values are the same in both languages.", "enum": [ "en", "ar" ], "default": "en" }, "required": false, "description": "**Response language.** Optional; defaults to `en`.\n\n- `en` — English\n- `ar` — Arabic\n\nChanges labels, titles and descriptions only; ids and numeric values are the same in both languages.", "name": "lang", "in": "query" } ], "responses": { "200": { "description": "**The finance providers that finance new cars**, optionally for one make — the `finance_provider_id` values `/new-cars` takes.\n\n- Rows are the providers as published: `id`, `company_name`, `logo`, `description`, `phone`, `whatsapp`.\n- A new-car row's provider is its `financing_company_id`.\n- Ids are per market: call this with the `country` you will search.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MotorySuccessResponseSchema" }, "example": { "success": true, "data": { "items": [ { "id": 143, "company_name": "Automotive Distribution & Marketing Co. Ltd.", "logo": null, "description": "Contact the dealer's customer service for any inquiries or concerns you may have", "phone": null, "whatsapp": "" } ] } } } } }, "400": { "description": "Bad request — a parameter is missing, malformed or out of range", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MotoryErrorResponseSchema" } } } }, "404": { "description": "Not found — the requested id or link does not exist", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MotoryErrorResponseSchema" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MotoryErrorResponseSchema" } } } }, "503": { "description": "Service busy — retry shortly", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MotoryErrorResponseSchema" } } } } } } }, "/fuel-prices": { "get": { "tags": [ "Reference" ], "operationId": "getFuelPrices", "description": "Read the retail fuel prices per litre for Saudi Arabia or Jordan, one entry per fuel grade, with the month of the last update. Takes only country and lang, so no id is needed from another call.", "parameters": [ { "schema": { "type": "string", "description": "**Market to read.** Optional; defaults to `sa`.\n\n- `sa` — Saudi Arabia (prices in SAR)\n- `jo` — Jordan (prices in JOD)\n\nEach market has its own inventory and its own ids (makes, models, cities, body types, dealers, vehicles). Send only ids from a call made with the same `country`. An id from the other market is answered as an unknown id:\n\n- **404** — a lookup by id: every details route, `/models`, `/finance-providers`, and `category_id` on `/category-news` and `/videos`.\n- **400 naming the param** — `make_id`, `model_id` and `finance_provider_id` on `/new-cars` and `/new-car-filters`; `make_id` and `city_id` on `/dealers`; `make_id` and `company_id` on `/offers`; `make_id`, `author_id` and `category_id` as filters of the news lists, and `make_id` on `/videos` (on `/tag-news`, an unknown `author_id` with a tag that is not a make returns an empty list when the tag has articles in the requested `lang`, and 404 otherwise).\n- **Empty result** — every other id filter, for example `body_type_id`, `fuel_type_id`, `transmission_id` or `origin_id` on `/new-cars`, every `/used-cars` and `/used-car-filters` filter, and `dealer_id` on `/dealers`.", "enum": [ "sa", "jo" ], "default": "sa" }, "required": false, "description": "**Market to read.** Optional; defaults to `sa`.\n\n- `sa` — Saudi Arabia (prices in SAR)\n- `jo` — Jordan (prices in JOD)\n\nEach market has its own inventory and its own ids (makes, models, cities, body types, dealers, vehicles). Send only ids from a call made with the same `country`. An id from the other market is answered as an unknown id:\n\n- **404** — a lookup by id: every details route, `/models`, `/finance-providers`, and `category_id` on `/category-news` and `/videos`.\n- **400 naming the param** — `make_id`, `model_id` and `finance_provider_id` on `/new-cars` and `/new-car-filters`; `make_id` and `city_id` on `/dealers`; `make_id` and `company_id` on `/offers`; `make_id`, `author_id` and `category_id` as filters of the news lists, and `make_id` on `/videos` (on `/tag-news`, an unknown `author_id` with a tag that is not a make returns an empty list when the tag has articles in the requested `lang`, and 404 otherwise).\n- **Empty result** — every other id filter, for example `body_type_id`, `fuel_type_id`, `transmission_id` or `origin_id` on `/new-cars`, every `/used-cars` and `/used-car-filters` filter, and `dealer_id` on `/dealers`.", "name": "country", "in": "query" }, { "schema": { "type": "string", "description": "**Response language.** Optional; defaults to `en`.\n\n- `en` — English\n- `ar` — Arabic\n\nChanges labels, titles and descriptions only; ids and numeric values are the same in both languages.", "enum": [ "en", "ar" ], "default": "en" }, "required": false, "description": "**Response language.** Optional; defaults to `en`.\n\n- `en` — English\n- `ar` — Arabic\n\nChanges labels, titles and descriptions only; ids and numeric values are the same in both languages.", "name": "lang", "in": "query" } ], "responses": { "200": { "description": "**The retail fuel prices the marketplace publishes** for the selected market (Saudi Arabia or Jordan). Served as-is:\n\n- `title`\n- `sub_title` — the month of the last update and the unit, for example SAR or JOD per litre\n- `list` — one entry per fuel grade: `title` is the grade and `description` the price per litre as published text", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MotorySuccessResponseSchema" }, "example": { "success": true, "data": { "title": "Fuel prices in Saudi Arabia", "sub_title": "Latest update: June 2026 (SR/liter)", "list": [ { "title": "Gasoline 91", "description": "2.180" } ] } } } } }, "400": { "description": "Bad request — a parameter is missing, malformed or out of range", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MotoryErrorResponseSchema" } } } }, "404": { "description": "Not found — the requested id or link does not exist", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MotoryErrorResponseSchema" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MotoryErrorResponseSchema" } } } }, "503": { "description": "Service busy — retry shortly", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MotoryErrorResponseSchema" } } } } } } }, "/used-cars": { "get": { "tags": [ "Used Cars" ], "operationId": "searchUsedCars", "description": "Search used cars for sale in Saudi Arabia or Jordan by make, model, city, year, price, body, fuel, transmission, mileage, colour, origin, electric range, seller type, dealer, financing and keyword, with seven sort orders. Take filter ids from /makes and /used-car-filters; open a row in /used-car-details.", "parameters": [ { "schema": { "type": "string", "description": "**Market to read.** Optional; defaults to `sa`.\n\n- `sa` — Saudi Arabia (prices in SAR)\n- `jo` — Jordan (prices in JOD)\n\nEach market has its own inventory and its own ids (makes, models, cities, body types, dealers, vehicles). Send only ids from a call made with the same `country`. An id from the other market is answered as an unknown id:\n\n- **404** — a lookup by id: every details route, `/models`, `/finance-providers`, and `category_id` on `/category-news` and `/videos`.\n- **400 naming the param** — `make_id`, `model_id` and `finance_provider_id` on `/new-cars` and `/new-car-filters`; `make_id` and `city_id` on `/dealers`; `make_id` and `company_id` on `/offers`; `make_id`, `author_id` and `category_id` as filters of the news lists, and `make_id` on `/videos` (on `/tag-news`, an unknown `author_id` with a tag that is not a make returns an empty list when the tag has articles in the requested `lang`, and 404 otherwise).\n- **Empty result** — every other id filter, for example `body_type_id`, `fuel_type_id`, `transmission_id` or `origin_id` on `/new-cars`, every `/used-cars` and `/used-car-filters` filter, and `dealer_id` on `/dealers`.", "enum": [ "sa", "jo" ], "default": "sa" }, "required": false, "description": "**Market to read.** Optional; defaults to `sa`.\n\n- `sa` — Saudi Arabia (prices in SAR)\n- `jo` — Jordan (prices in JOD)\n\nEach market has its own inventory and its own ids (makes, models, cities, body types, dealers, vehicles). Send only ids from a call made with the same `country`. An id from the other market is answered as an unknown id:\n\n- **404** — a lookup by id: every details route, `/models`, `/finance-providers`, and `category_id` on `/category-news` and `/videos`.\n- **400 naming the param** — `make_id`, `model_id` and `finance_provider_id` on `/new-cars` and `/new-car-filters`; `make_id` and `city_id` on `/dealers`; `make_id` and `company_id` on `/offers`; `make_id`, `author_id` and `category_id` as filters of the news lists, and `make_id` on `/videos` (on `/tag-news`, an unknown `author_id` with a tag that is not a make returns an empty list when the tag has articles in the requested `lang`, and 404 otherwise).\n- **Empty result** — every other id filter, for example `body_type_id`, `fuel_type_id`, `transmission_id` or `origin_id` on `/new-cars`, every `/used-cars` and `/used-car-filters` filter, and `dealer_id` on `/dealers`.", "name": "country", "in": "query" }, { "schema": { "type": "string", "description": "**Response language.** Optional; defaults to `en`.\n\n- `en` — English\n- `ar` — Arabic\n\nChanges labels, titles and descriptions only; ids and numeric values are the same in both languages.", "enum": [ "en", "ar" ], "default": "en" }, "required": false, "description": "**Response language.** Optional; defaults to `en`.\n\n- `en` — English\n- `ar` — Arabic\n\nChanges labels, titles and descriptions only; ids and numeric values are the same in both languages.", "name": "lang", "in": "query" }, { "schema": { "type": "string", "description": "**Make filter.** Optional; one or more make ids, comma-separated (for example `90,71`). A car matching any listed make is kept.\n\nTake ids from `/makes` called with the same `country`." }, "required": false, "description": "**Make filter.** Optional; one or more make ids, comma-separated (for example `90,71`). A car matching any listed make is kept.\n\nTake ids from `/makes` called with the same `country`.", "name": "make_id", "in": "query" }, { "schema": { "type": "string", "description": "**Model filter.** Optional; one or more model ids, comma-separated. A car matching any listed model is kept.\n\nTake ids from `/models`. Works without `make_id`; combined with it, only the listed models are kept (a make with none of its models listed drops out)." }, "required": false, "description": "**Model filter.** Optional; one or more model ids, comma-separated. A car matching any listed model is kept.\n\nTake ids from `/models`. Works without `make_id`; combined with it, only the listed models are kept (a make with none of its models listed drops out).", "name": "model_id", "in": "query" }, { "schema": { "type": "string", "description": "**City filter.** Optional; one or more ids, comma-separated; any listed value matches.\n\nTake ids from `/used-car-filters` (cities) called with the same `country`." }, "required": false, "description": "**City filter.** Optional; one or more ids, comma-separated; any listed value matches.\n\nTake ids from `/used-car-filters` (cities) called with the same `country`.", "name": "city_id", "in": "query" }, { "schema": { "type": "integer", "description": "**Earliest model year.** Optional; for example `2020`.\n\nCombine with `max_year` for a range (equal values select one year). `min_year` greater than `max_year` is rejected with 400.", "minimum": 1900, "maximum": 2100 }, "required": false, "description": "**Earliest model year.** Optional; for example `2020`.\n\nCombine with `max_year` for a range (equal values select one year). `min_year` greater than `max_year` is rejected with 400.", "name": "min_year", "in": "query" }, { "schema": { "type": "integer", "description": "**Latest model year.** Optional; for example `2024`.\n\nCombine with `min_year` for a range. `max_year` lower than `min_year` is rejected with 400.", "minimum": 1900, "maximum": 2100 }, "required": false, "description": "**Latest model year.** Optional; for example `2024`.\n\nCombine with `min_year` for a range. `max_year` lower than `min_year` is rejected with 400.", "name": "max_year", "in": "query" }, { "schema": { "type": "integer", "description": "**Minimum asking price**, whole number in the market currency (SAR for `sa`, JOD for `jo`). Optional.\n\nAny price bound keeps only listings that show a price — listings whose price reads \"Contact Seller\" are excluded. `min_price` greater than `max_price` is rejected with 400.", "minimum": 0, "maximum": 100000000 }, "required": false, "description": "**Minimum asking price**, whole number in the market currency (SAR for `sa`, JOD for `jo`). Optional.\n\nAny price bound keeps only listings that show a price — listings whose price reads \"Contact Seller\" are excluded. `min_price` greater than `max_price` is rejected with 400.", "name": "min_price", "in": "query" }, { "schema": { "type": "integer", "description": "**Maximum asking price**, whole number in the market currency (SAR for `sa`, JOD for `jo`). Optional.\n\nAny price bound keeps only listings that show a price. Send `max_price` alone for \"up to\", both bounds for a band.", "minimum": 1, "maximum": 100000000 }, "required": false, "description": "**Maximum asking price**, whole number in the market currency (SAR for `sa`, JOD for `jo`). Optional.\n\nAny price bound keeps only listings that show a price. Send `max_price` alone for \"up to\", both bounds for a band.", "name": "max_price", "in": "query" }, { "schema": { "type": "string", "description": "**Body type filter (SUV, Sedan, Hatchback…).** Optional; one or more ids, comma-separated; any listed value matches.\n\nTake ids from `/used-car-filters` (body types) called with the same `country`." }, "required": false, "description": "**Body type filter (SUV, Sedan, Hatchback…).** Optional; one or more ids, comma-separated; any listed value matches.\n\nTake ids from `/used-car-filters` (body types) called with the same `country`.", "name": "body_type_id", "in": "query" }, { "schema": { "type": "string", "description": "**Fuel type filter (Gasoline, Hybrid, Electric, Diesel…).** Optional; one or more ids, comma-separated; any listed value matches.\n\nTake ids from `/used-car-filters` (fuel types) called with the same `country`." }, "required": false, "description": "**Fuel type filter (Gasoline, Hybrid, Electric, Diesel…).** Optional; one or more ids, comma-separated; any listed value matches.\n\nTake ids from `/used-car-filters` (fuel types) called with the same `country`.", "name": "fuel_type_id", "in": "query" }, { "schema": { "type": "string", "description": "**Transmission filter (Automatic, Manual, CVT…).** Optional; one or more ids, comma-separated; any listed value matches.\n\nTake ids from `/used-car-filters` (transmissions) called with the same `country`." }, "required": false, "description": "**Transmission filter (Automatic, Manual, CVT…).** Optional; one or more ids, comma-separated; any listed value matches.\n\nTake ids from `/used-car-filters` (transmissions) called with the same `country`.", "name": "transmission_id", "in": "query" }, { "schema": { "type": "string", "description": "**Mileage band filter (for example \"0 km\", \"10,000-19,999 km\", \"200,000+ km\").** Optional; one or more ids, comma-separated; any listed value matches.\n\nTake ids from `/used-car-filters` (mileage bands) called with the same `country`." }, "required": false, "description": "**Mileage band filter (for example \"0 km\", \"10,000-19,999 km\", \"200,000+ km\").** Optional; one or more ids, comma-separated; any listed value matches.\n\nTake ids from `/used-car-filters` (mileage bands) called with the same `country`.", "name": "mileage_id", "in": "query" }, { "schema": { "type": "string", "description": "**Exterior colour filter.** Optional; one or more ids, comma-separated; any listed value matches.\n\nTake ids from `/used-car-filters` (colours) called with the same `country`." }, "required": false, "description": "**Exterior colour filter.** Optional; one or more ids, comma-separated; any listed value matches.\n\nTake ids from `/used-car-filters` (colours) called with the same `country`.", "name": "color_id", "in": "query" }, { "schema": { "type": "string", "description": "**Manufacturer origin filter (Chinese, Japanese, German, Korean, American…).** Optional; one or more ids, comma-separated; any listed value matches.\n\nTake ids from `/used-car-filters` (origins) called with the same `country`." }, "required": false, "description": "**Manufacturer origin filter (Chinese, Japanese, German, Korean, American…).** Optional; one or more ids, comma-separated; any listed value matches.\n\nTake ids from `/used-car-filters` (origins) called with the same `country`.", "name": "origin_id", "in": "query" }, { "schema": { "type": "boolean", "description": "**Only cars offered with financing.** Optional.\n\n- `true` — keep only listings with financing available\n- omitted — all listings\n\n`false` is rejected with 400: there is no \"without financing\" filter.\n\nIn a market whose used listings carry no financing, `has_financing=true` returns no listings.", "example": "" }, "required": false, "description": "**Only cars offered with financing.** Optional.\n\n- `true` — keep only listings with financing available\n- omitted — all listings\n\n`false` is rejected with 400: there is no \"without financing\" filter.\n\nIn a market whose used listings carry no financing, `has_financing=true` returns no listings.", "name": "has_financing", "in": "query" }, { "schema": { "type": "boolean", "description": "**Only cars that show a price.** Optional.\n\n- `true` — drop listings whose price reads \"Contact Seller\"\n- omitted — all listings\n\n`false` is rejected with 400.", "example": "" }, "required": false, "description": "**Only cars that show a price.** Optional.\n\n- `true` — drop listings whose price reads \"Contact Seller\"\n- omitted — all listings\n\n`false` is rejected with 400.", "name": "with_price_only", "in": "query" }, { "schema": { "type": "string", "description": "**Seller type.** Optional; omitted returns both.\n\n- `dealer` — dealerships and showrooms\n- `individual` — private sellers", "enum": [ "dealer", "individual" ] }, "required": false, "description": "**Seller type.** Optional; omitted returns both.\n\n- `dealer` — dealerships and showrooms\n- `individual` — private sellers", "name": "seller_type", "in": "query" }, { "schema": { "type": "string", "description": "**Dealers' stock only.** Optional; one or more dealer ids, comma-separated (for example `283165,496563`). A car listed by any of them is kept.\n\nTake `dealer_id` from `/dealers`, `seller_id` from a `/used-cars` row, or a `dealer` option of `/used-car-filters`. This is a dealer's whole stock, including zero-mileage cars; `/new-cars` has no dealer filter." }, "required": false, "description": "**Dealers' stock only.** Optional; one or more dealer ids, comma-separated (for example `283165,496563`). A car listed by any of them is kept.\n\nTake `dealer_id` from `/dealers`, `seller_id` from a `/used-cars` row, or a `dealer` option of `/used-car-filters`. This is a dealer's whole stock, including zero-mileage cars; `/new-cars` has no dealer filter.", "name": "dealer_id", "in": "query" }, { "schema": { "type": "string", "description": "**Free-text search** within used listings, for example `camry` or `land cruiser`. Optional.\n\nMatches listing text such as make and model names, in the language selected by `lang` only: Arabic text (`تويوتا`) matches with `lang=ar`, English text with `lang=en`. Combine with any other filter.", "maxLength": 100 }, "required": false, "description": "**Free-text search** within used listings, for example `camry` or `land cruiser`. Optional.\n\nMatches listing text such as make and model names, in the language selected by `lang` only: Arabic text (`تويوتا`) matches with `lang=ar`, English text with `lang=en`. Combine with any other filter.", "name": "keyword", "in": "query" }, { "schema": { "type": "string", "description": "**Price collection.** Optional; one value.\n\n- `cars-with-prices` — listings that show a price\n- `price-reduced-cars` — listings whose price was reduced\n- `lease-transfer-cars` — lease-transfer offers\n- `used-cars-financing` — listings with financing available\n\n`used-cars-financing` keeps the same listings as `has_financing=true`. In a market whose used listings carry no financing, `pricing=used-cars-financing` returns no listings.", "enum": [ "cars-with-prices", "price-reduced-cars", "lease-transfer-cars", "used-cars-financing" ] }, "required": false, "description": "**Price collection.** Optional; one value.\n\n- `cars-with-prices` — listings that show a price\n- `price-reduced-cars` — listings whose price was reduced\n- `lease-transfer-cars` — lease-transfer offers\n- `used-cars-financing` — listings with financing available\n\n`used-cars-financing` keeps the same listings as `has_financing=true`. In a market whose used listings carry no financing, `pricing=used-cars-financing` returns no listings.", "name": "pricing", "in": "query" }, { "schema": { "type": "integer", "description": "**Minimum electric range**, whole kilometres per full charge. Optional.\n\n- Any bound keeps only cars with a published electric range (electric cars, plug-in and range-extender hybrids).\n- Both bounds are inclusive.\n- `min_electric_range` greater than `max_electric_range` is rejected with 400.", "minimum": 0, "maximum": 10000 }, "required": false, "description": "**Minimum electric range**, whole kilometres per full charge. Optional.\n\n- Any bound keeps only cars with a published electric range (electric cars, plug-in and range-extender hybrids).\n- Both bounds are inclusive.\n- `min_electric_range` greater than `max_electric_range` is rejected with 400.", "name": "min_electric_range", "in": "query" }, { "schema": { "type": "integer", "description": "**Maximum electric range**, whole kilometres per full charge. Optional.\n\n- Any bound keeps only cars with a published electric range (electric cars, plug-in and range-extender hybrids).\n- Both bounds are inclusive.\n- Send `max_electric_range` alone for \"up to\", both bounds for a band.", "minimum": 1, "maximum": 10000 }, "required": false, "description": "**Maximum electric range**, whole kilometres per full charge. Optional.\n\n- Any bound keeps only cars with a published electric range (electric cars, plug-in and range-extender hybrids).\n- Both bounds are inclusive.\n- Send `max_electric_range` alone for \"up to\", both bounds for a band.", "name": "max_electric_range", "in": "query" }, { "schema": { "type": "string", "description": "**Result order.** Optional; defaults to `featured`.\n\n- `featured` — promoted listings first (the marketplace's own order)\n- `newest` — most recently published first (by publish date, which can differ from the `created_at` date shown on a row)\n- `oldest` — earliest published first (by publish date, which can differ from the `created_at` date shown on a row)\n- `mileage_asc` — lowest mileage band first\n- `mileage_desc` — highest mileage band first\n- `price_asc` — cheapest first\n- `price_desc` — most expensive first\n\nPrice orders (`price_asc`, `price_desc`):\n\n- They order the whole result of a search that matches at most 50 listings, and `page` / `page_size` page through that ordered result.\n- A search that matches more listings returns 400 with its match count. Narrow it with `min_price` / `max_price` (the `price_range` option of `/used-car-filters` lists price bands with their counts) or other filters, or use another `sort`.\n- Listings with the same price are ordered newest first.\n- Listings that show no price (for example \"Contact Seller\") come last in both price orders, newest first. Send `with_price_only=true` to leave them out.", "enum": [ "featured", "newest", "oldest", "mileage_asc", "mileage_desc", "price_asc", "price_desc" ], "default": "featured" }, "required": false, "description": "**Result order.** Optional; defaults to `featured`.\n\n- `featured` — promoted listings first (the marketplace's own order)\n- `newest` — most recently published first (by publish date, which can differ from the `created_at` date shown on a row)\n- `oldest` — earliest published first (by publish date, which can differ from the `created_at` date shown on a row)\n- `mileage_asc` — lowest mileage band first\n- `mileage_desc` — highest mileage band first\n- `price_asc` — cheapest first\n- `price_desc` — most expensive first\n\nPrice orders (`price_asc`, `price_desc`):\n\n- They order the whole result of a search that matches at most 50 listings, and `page` / `page_size` page through that ordered result.\n- A search that matches more listings returns 400 with its match count. Narrow it with `min_price` / `max_price` (the `price_range` option of `/used-car-filters` lists price bands with their counts) or other filters, or use another `sort`.\n- Listings with the same price are ordered newest first.\n- Listings that show no price (for example \"Contact Seller\") come last in both price orders, newest first. Send `with_price_only=true` to leave them out.", "name": "sort", "in": "query" }, { "schema": { "type": "integer", "description": "**Page number, starting at 1.** Optional; defaults to `1`.\n\nKeep `page_size` fixed while paging and stop at `pagination.total_pages`. A `page` beyond the last page returns an empty `items` list.", "minimum": 1, "maximum": 10000, "default": 1 }, "required": false, "description": "**Page number, starting at 1.** Optional; defaults to `1`.\n\nKeep `page_size` fixed while paging and stop at `pagination.total_pages`. A `page` beyond the last page returns an empty `items` list.", "name": "page", "in": "query" }, { "schema": { "type": "integer", "description": "**Results per page.** Optional; defaults to `20`, accepts 1–50.\n\nValues above 50 are rejected with 400. Keep the same `page_size` on every page of one search so pages neither overlap nor skip results.", "minimum": 1, "maximum": 50, "default": 20 }, "required": false, "description": "**Results per page.** Optional; defaults to `20`, accepts 1–50.\n\nValues above 50 are rejected with 400. Keep the same `page_size` on every page of one search so pages neither overlap nor skip results.", "name": "page_size", "in": "query" } ], "responses": { "200": { "description": "**Search used cars for sale** in Saudi Arabia or Jordan, with make, model, city, year, price, body, fuel, transmission, mileage, colour, origin, electric range, seller, dealer and financing filters, and seven sort orders including price.\n\nEach row is a listing card as the marketplace serves it:\n\n- Title, make/model ids, year and city.\n- `mileage` as served: a band label (for example `\"200,000+ km\"`) or an exact figure (for example `\"92,319 km\"`).\n- `created_at` — the date shown on the listing, `DD/MM/YYYY` as served.\n- `price_object` — price, currency and financing flags.\n- Seller identity and published contact numbers, images and the public `share_link`.\n\nPaging and order:\n\n- `pagination.total_items` counts every match; a `page` past `pagination.total_pages` returns an empty `items` list.\n- `sort=newest` / `oldest` order by the date a listing was published, which can differ from the row's `created_at`.\n- `sort=price_asc` / `price_desc` order the whole result of a search that matches at most 50 listings, listings without a price last; a larger search returns 400 naming how to narrow it.\n\nRead a row `id` with `/used-car-details` for the full listing. Only listings currently for sale are returned. Ids are per market: send ids obtained with the same `country`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MotorySuccessResponseSchema" }, "example": { "success": true, "data": { "items": [ { "id": 281663, "is_featured": true, "package": { "title": "Nitrous Listing", "icon": "https://s3.eu-central-1.amazonaws.com/v3-common.motory.com/common/1710369915.3925-65f22c7b5fd5f.webp", "color": "#5B0DB3" }, "is_pre_owned": false, "title": "GAC GS4 2026", "price_object": { "hide_price": false, "price_text": "Selling Price", "price_value": "Contact Seller", "price_currency": "", "price_note": "", "monthly_payment": null, "down_payment": null, "final_payment": null, "total_amount": null, "period": 0, "has_financing": true, "finance_text": "Financing", "finance_value": "Available", "disabled_finance_value": false, "disabled_price_value": false, "finance_currency": "", "percentage": null, "show_finance_button": true, "show_cash_button": false, "show_call_button": true }, "is_favorite": false, "year": 2026, "make_id": 41, "model_id": 552, "status": "active", "make_logo": "https://s3.eu-central-1.amazonaws.com/v3-common.motory.com/taxonomy/l-1669880349.8924-63885a1dd9e1f.webp", "make": "GAC", "model": "GS4", "description": "Used GAC GS4 2026 car for sale with Automatic transmission. The mileage when the car is listed for sale is 501-9,999. The car also features an exterior color Grey. The car is currently located in Riyadh at SAR 0.", "rejected_reason": null, "created_at": "07/10/2026", "transmission": "Automatic", "mileage": "501-9,999 km", "city": "Riyadh", "bread_crumb_urls": null, "has_financing": true, "is_dealer": true, "seller_id": 755077, "seller_name": "Car Empire", "seller_phone": "+966599090002", "phone_numbers": [ { "phone": "+966599090002", "phone_name": "Car Empire" } ], "whatsapp_number": "+966599090002", "enable_whatsapp_phone": { "enable_whats_app": true, "enable_phone": true }, "dealer_type": "Dealer", "dealer_type_url": null, "is_motory_shop": false, "motory_shop_icon": null, "motory_shop_link": null, "show_financing_info": false, "is_lexus": false, "financing_company_id": 334, "financing_company_name": "Car empire ", "financing_company_logo": "https://s3.eu-central-1.amazonaws.com/v3-companies.motory.com/lead-company/l-1766253325.1136-6946e30d1bbd7.webp", "preferred_financing_company_phone": "+966599090002", "preferred_financing_company_cities": [], "preferred_financing_company_periods": [], "down_payment": null, "final_payment": null, "total_amount": null, "percentage": { "down_payment_percentage": null, "monthly_payment_percentage": null, "final_payment_percentage": null }, "period": 0, "lexus_purchase_types_list": [ { "value": "cash", "text": "Cash", "show_component": null, "hide_component": [ "downpayment" ] }, { "value": "finance", "text": "Finance", "show_component": [ "downpayment" ], "hide_component": null } ], "overview_details_4": [ { "is_image": true, "text": "GAC", "image": "https://s3.eu-central-1.amazonaws.com/v3-common.motory.com/taxonomy/l-1669880349.8924-63885a1dd9e1f.webp" } ], "overview_details_2": [ { "is_image": true, "text": "SUV", "image": "https://ksa.motory.com/images/overview_icons/body_type.png" } ], "overview": [ { "is_image": true, "text": "GAC", "image": "https://s3.eu-central-1.amazonaws.com/v3-common.motory.com/taxonomy/l-1669880349.8924-63885a1dd9e1f.webp" } ], "disclaimer": { "title": "Disclaimer", "description": "Motory is not responsible for any financial transactions between the seller and the buyer, and you will not be required to fill in additional private information using any other links", "description2": "Before making a purchase, make sure to verify the seller's identity. Also, you should never transfer money in advance", "description3": "For a safe experience, the financial transactions must be done in person through the official channels" }, "whats_app_disclaimer": { "title": "Disclaimer", "description": "Motory is not responsible for any financial transactions between the seller and the buyer, and you will not be required to fill in additional private information using any other links", "description2": "Before making a purchase, make sure to verify the seller's identity. Also, you should never transfer money in advance", "description3": "For a safe experience, the financial transactions must be done in person through the official channels" }, "call_disclaimer": { "title": "Disclaimer", "description": "Motory is not responsible for any financial transactions between the seller and the buyer, and you will not be required to fill in additional private information using any other links", "description2": "Before making a purchase, make sure to verify the seller's identity. Also, you should never transfer money in advance", "description3": "For a safe experience, the financial transactions must be done in person through the official channels" }, "features": null, "can_edit": true, "images": [ "https://s3.eu-central-1.amazonaws.com/v3-cfs.motory.com/vehicle-used/l-1791381190.4736-6ac64ec6739f0.webp" ], "images_full": [ "https://s3.eu-central-1.amazonaws.com/v3-cfs.motory.com/vehicle-used/l-1791381190.4736-6ac64ec6739f0.webp" ], "is_vat_company": false, "is_vat_vehicle": true, "companies": [ { "id": 334, "name": "Car empire ", "price": 0, "is_vat": true, "phone": "+966599090002", "logo": "https://s3.eu-central-1.amazonaws.com/v3-companies.motory.com/lead-company/l-1766253325.1136-6946e30d1bbd7.webp", "small_logo": "https://s3.eu-central-1.amazonaws.com/v3-companies.motory.com/lead-company/l-1766253312.0995-6946e300184d2.webp" } ], "vat_text": "VAT Included", "warranty_text": "5 Years Warranty", "images_count": "1 Pics", "cell_type": "form_only", "cash_sale_companies": null, "extra_purchase_plan_list": [], "extra_gender_list": [], "extra_model_list": [], "extra_expected_time_to_buy_list": [], "currency": "SR", "per_month": "per month", "share_link": "https://ksa.motory.com/en/cars-for-sale/riyadh-haraj/gac/gs4/2026/281663/", "url": null, "is_not_available": false, "not_available_text": null }, { "id": 281210, "is_featured": true, "package": { "title": "Nitrous Listing", "icon": "https://s3.eu-central-1.amazonaws.com/v3-common.motory.com/common/1710369915.3925-65f22c7b5fd5f.webp", "color": "#5B0DB3" }, "is_pre_owned": false, "title": "KIA Pegas 2025", "price_object": { "hide_price": false, "price_text": "Selling Price", "price_value": "Contact Seller", "price_currency": "", "price_note": "", "monthly_payment": null, "down_payment": null, "final_payment": null, "total_amount": null, "period": 0, "has_financing": true, "finance_text": "Financing", "finance_value": "Available", "disabled_finance_value": false, "disabled_price_value": false, "finance_currency": "", "percentage": null, "show_finance_button": true, "show_cash_button": false, "show_call_button": true }, "is_favorite": false, "year": 2025, "make_id": 71, "model_id": 266, "status": "active", "make_logo": "https://s3.eu-central-1.amazonaws.com/v3-common.motory.com/taxonomy/l-1669878484.7524-638852d4b7b24.webp", "make": "KIA", "model": "Pegas", "description": "New KIA Pegas 2025 car for sale with Automatic transmission. The mileage when the car is listed for sale is 0. The car also features an exterior color Dark Grey. The car is currently located in Riyadh at SAR 0.", "rejected_reason": null, "created_at": "22/09/2026", "transmission": "Automatic", "mileage": "0 km", "city": "Riyadh", "bread_crumb_urls": null, "has_financing": true, "is_dealer": true, "seller_id": 755077, "seller_name": "Car Empire", "seller_phone": "+966599090002", "phone_numbers": [ { "phone": "+966599090002", "phone_name": "Car Empire" } ], "whatsapp_number": "+966599090002", "enable_whatsapp_phone": { "enable_whats_app": true, "enable_phone": true }, "dealer_type": "Dealer", "dealer_type_url": null, "is_motory_shop": false, "motory_shop_icon": null, "motory_shop_link": null, "show_financing_info": false, "is_lexus": false, "financing_company_id": 334, "financing_company_name": "Car empire ", "financing_company_logo": "https://s3.eu-central-1.amazonaws.com/v3-companies.motory.com/lead-company/l-1766253325.1136-6946e30d1bbd7.webp", "preferred_financing_company_phone": "+966599090002", "preferred_financing_company_cities": [], "preferred_financing_company_periods": [], "down_payment": null, "final_payment": null, "total_amount": null, "percentage": { "down_payment_percentage": null, "monthly_payment_percentage": null, "final_payment_percentage": null }, "period": 0, "lexus_purchase_types_list": [ { "value": "cash", "text": "Cash", "show_component": null, "hide_component": [ "downpayment" ] }, { "value": "finance", "text": "Finance", "show_component": [ "downpayment" ], "hide_component": null } ], "overview_details_4": [ { "is_image": true, "text": "KIA", "image": "https://s3.eu-central-1.amazonaws.com/v3-common.motory.com/taxonomy/l-1669878484.7524-638852d4b7b24.webp" } ], "overview_details_2": [ { "is_image": true, "text": "Sedan", "image": "https://ksa.motory.com/images/overview_icons/body_type.png" } ], "overview": [ { "is_image": true, "text": "KIA", "image": "https://s3.eu-central-1.amazonaws.com/v3-common.motory.com/taxonomy/l-1669878484.7524-638852d4b7b24.webp" } ], "disclaimer": { "title": "Disclaimer", "description": "Motory is not responsible for any financial transactions between the seller and the buyer, and you will not be required to fill in additional private information using any other links", "description2": "Before making a purchase, make sure to verify the seller's identity. Also, you should never transfer money in advance", "description3": "For a safe experience, the financial transactions must be done in person through the official channels" }, "whats_app_disclaimer": { "title": "Disclaimer", "description": "Motory is not responsible for any financial transactions between the seller and the buyer, and you will not be required to fill in additional private information using any other links", "description2": "Before making a purchase, make sure to verify the seller's identity. Also, you should never transfer money in advance", "description3": "For a safe experience, the financial transactions must be done in person through the official channels" }, "call_disclaimer": { "title": "Disclaimer", "description": "Motory is not responsible for any financial transactions between the seller and the buyer, and you will not be required to fill in additional private information using any other links", "description2": "Before making a purchase, make sure to verify the seller's identity. Also, you should never transfer money in advance", "description3": "For a safe experience, the financial transactions must be done in person through the official channels" }, "features": null, "can_edit": true, "images": [ "https://s3.eu-central-1.amazonaws.com/v3-cfs.motory.com/vehicle-used/l-1790084833.0465-6ab286e10b586.webp" ], "images_full": [ "https://s3.eu-central-1.amazonaws.com/v3-cfs.motory.com/vehicle-used/l-1790084833.0465-6ab286e10b586.webp" ], "is_vat_company": false, "is_vat_vehicle": true, "companies": [ { "id": 334, "name": "Car empire ", "price": 0, "is_vat": true, "phone": "+966599090002", "logo": "https://s3.eu-central-1.amazonaws.com/v3-companies.motory.com/lead-company/l-1766253325.1136-6946e30d1bbd7.webp", "small_logo": "https://s3.eu-central-1.amazonaws.com/v3-companies.motory.com/lead-company/l-1766253312.0995-6946e300184d2.webp" } ], "vat_text": "VAT Included", "warranty_text": "3 Years Warranty", "images_count": "1 Pics", "cell_type": "form_only", "cash_sale_companies": [ { "id": 4, "name": "Kia AlJabr", "phone": "+966920014200", "logo": "https://s3.eu-central-1.amazonaws.com/v3-companies.motory.com/company-cash-sale/l-1605479865.9629-5fb1adb9eb14a.webp", "small_logo": "https://s3.eu-central-1.amazonaws.com/v3-companies.motory.com/company-cash-sale/l-1605479866.6855-5fb1adbaa75c6.webp", "cities": [ { "id": 805, "name": "الخرج", "branches": [] }, { "id": 810, "name": "الرياض", "branches": [ { "id": 1282, "name": "Telesales - Central" } ] } ], "extra_fields": { "extra_purchase_plan": false, "extra_gender": false, "extra_model": false, "extra_expected_time_to_buy": true } } ], "extra_purchase_plan_list": [], "extra_gender_list": [], "extra_model_list": [], "extra_expected_time_to_buy_list": [ { "id": 2849, "name": "Immediate" } ], "currency": "SR", "per_month": "per month", "share_link": "https://ksa.motory.com/en/cars-for-sale/riyadh-haraj/kia/pegas/2025/281210/", "url": null, "is_not_available": false, "not_available_text": null }, { "id": 272972, "is_featured": false, "package": null, "is_pre_owned": false, "title": "Changan UNI-S 2026", "price_object": { "hide_price": false, "price_text": "Selling Price", "price_value": "Contact Seller", "price_currency": "", "price_note": "", "monthly_payment": null, "down_payment": null, "final_payment": null, "total_amount": null, "period": 0, "has_financing": true, "finance_text": "Financing", "finance_value": "Available", "disabled_finance_value": false, "disabled_price_value": false, "finance_currency": "", "percentage": null, "show_finance_button": true, "show_cash_button": false, "show_call_button": true }, "is_favorite": false, "year": 2026, "make_id": 83, "model_id": 7695, "status": "active", "make_logo": "https://s3.eu-central-1.amazonaws.com/v3-common.motory.com/taxonomy/l-1669879004.5216-638854dc7f592.webp", "make": "Changan", "model": "UNI-S", "description": "New Changan UNI-S 2026 car for sale with Automatic transmission. The mileage when the car is listed for sale is 0. The car also features an exterior color Grey. The car is currently located in Riyadh at SAR 0.", "rejected_reason": null, "created_at": "18/12/2025", "transmission": "Automatic", "mileage": "0 km", "city": "Riyadh", "bread_crumb_urls": null, "has_financing": true, "is_dealer": true, "seller_id": 750286, "seller_name": "Cars Online Company", "seller_phone": "+966599271070", "phone_numbers": [ { "phone": "+966599271070", "phone_name": "Cars Online Company" } ], "whatsapp_number": "+966548959780", "enable_whatsapp_phone": { "enable_whats_app": true, "enable_phone": true }, "dealer_type": "Dealer", "dealer_type_url": null, "is_motory_shop": false, "motory_shop_icon": null, "motory_shop_link": null, "show_financing_info": false, "is_lexus": false, "financing_company_id": 332, "financing_company_name": "Cars Online Company", "financing_company_logo": "https://s3.eu-central-1.amazonaws.com/v3-companies.motory.com/lead-company/l-1764678738.8104-692edc52c5d89.webp", "preferred_financing_company_phone": "+966548959780", "preferred_financing_company_cities": [], "preferred_financing_company_periods": [], "down_payment": null, "final_payment": null, "total_amount": null, "percentage": { "down_payment_percentage": null, "monthly_payment_percentage": null, "final_payment_percentage": null }, "period": 0, "lexus_purchase_types_list": [ { "value": "cash", "text": "Cash", "show_component": null, "hide_component": [ "downpayment" ] }, { "value": "finance", "text": "Finance", "show_component": [ "downpayment" ], "hide_component": null } ], "overview_details_4": [ { "is_image": true, "text": "Changan", "image": "https://s3.eu-central-1.amazonaws.com/v3-common.motory.com/taxonomy/l-1669879004.5216-638854dc7f592.webp" } ], "overview_details_2": [ { "is_image": true, "text": "SUV", "image": "https://ksa.motory.com/images/overview_icons/body_type.png" } ], "overview": [ { "is_image": true, "text": "Changan", "image": "https://s3.eu-central-1.amazonaws.com/v3-common.motory.com/taxonomy/l-1669879004.5216-638854dc7f592.webp" } ], "disclaimer": { "title": "Disclaimer", "description": "Motory is not responsible for any financial transactions between the seller and the buyer, and you will not be required to fill in additional private information using any other links", "description2": "Before making a purchase, make sure to verify the seller's identity. Also, you should never transfer money in advance", "description3": "For a safe experience, the financial transactions must be done in person through the official channels" }, "whats_app_disclaimer": { "title": "Disclaimer", "description": "Motory is not responsible for any financial transactions between the seller and the buyer, and you will not be required to fill in additional private information using any other links", "description2": "Before making a purchase, make sure to verify the seller's identity. Also, you should never transfer money in advance", "description3": "For a safe experience, the financial transactions must be done in person through the official channels" }, "call_disclaimer": { "title": "Disclaimer", "description": "Motory is not responsible for any financial transactions between the seller and the buyer, and you will not be required to fill in additional private information using any other links", "description2": "Before making a purchase, make sure to verify the seller's identity. Also, you should never transfer money in advance", "description3": "For a safe experience, the financial transactions must be done in person through the official channels" }, "features": null, "can_edit": true, "images": [ "https://s3.eu-central-1.amazonaws.com/v3-cfs.motory.com/vehicle-used/l-1765994749.125-6942f0fd1e82e.webp" ], "images_full": [ "https://s3.eu-central-1.amazonaws.com/v3-cfs.motory.com/vehicle-used/l-1765994749.125-6942f0fd1e82e.webp" ], "is_vat_company": false, "is_vat_vehicle": true, "companies": [ { "id": 332, "name": "Cars Online Company", "price": 0, "is_vat": true, "phone": "+966548959780", "logo": "https://s3.eu-central-1.amazonaws.com/v3-companies.motory.com/lead-company/l-1764678738.8104-692edc52c5d89.webp", "small_logo": "https://s3.eu-central-1.amazonaws.com/v3-companies.motory.com/lead-company/l-1764678745.5057-692edc597b78b_outbound.webp" } ], "vat_text": "VAT Included", "warranty_text": "6 Years Warranty", "images_count": "11 Pics", "cell_type": "form_only", "cash_sale_companies": [ { "id": 22, "name": "Almajdouie - Changan", "phone": "+966920019992", "logo": "https://s3.eu-central-1.amazonaws.com/v3-companies.motory.com/company-cash-sale/l-1627889871.9199-6107a0cfe0959.webp", "small_logo": "https://s3.eu-central-1.amazonaws.com/v3-companies.motory.com/company-cash-sale/l-1627889869.6628-6107a0cda1d41.webp", "cities": [ { "id": "805", "name": "AlKharj", "branches": [ { "id": 690, "name": "Changan Almajdouie Riyadh - Exit 13 - Showroom" } ] } ], "extra_fields": { "extra_purchase_plan": true, "extra_gender": true, "extra_model": false, "extra_expected_time_to_buy": false } } ], "extra_purchase_plan_list": [ { "id": "7963", "name": "Just Asking" } ], "extra_gender_list": [ { "id": "1", "name": "MALE" } ], "extra_model_list": [], "extra_expected_time_to_buy_list": [], "currency": "SR", "per_month": "per month", "share_link": "https://ksa.motory.com/en/cars-for-sale/riyadh-haraj/changan/uni-s/2026/272972/", "url": null, "is_not_available": false, "not_available_text": null } ], "pagination": { "page": 1, "page_size": 20, "total_items": 1393, "total_pages": 70 } } } } } }, "400": { "description": "Bad request — a parameter is missing, malformed or out of range", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MotoryErrorResponseSchema" } } } }, "404": { "description": "Not found — the requested id or link does not exist", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MotoryErrorResponseSchema" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MotoryErrorResponseSchema" } } } }, "503": { "description": "Service busy — retry shortly", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MotoryErrorResponseSchema" } } } } } } }, "/used-car-details": { "get": { "tags": [ "Used Cars" ], "operationId": "getUsedCarDetails", "description": "Read one used-car listing in full: specs, VIN, gallery, price, the seller's phone and WhatsApp numbers, inspection reports and related cars. Takes a vehicle_id, the id of a /used-cars row.", "parameters": [ { "schema": { "type": "integer", "description": "**Used listing id.** Required; for example `272443`.\n\nTake `id` from a `/used-cars` row (or `vehicle_id` from a `related_used` item) fetched with the same `country`. An unknown id, or an id from the other market, returns 404.", "minimum": 1, "example": 272443 }, "required": true, "description": "**Used listing id.** Required; for example `272443`.\n\nTake `id` from a `/used-cars` row (or `vehicle_id` from a `related_used` item) fetched with the same `country`. An unknown id, or an id from the other market, returns 404.", "name": "vehicle_id", "in": "query" }, { "schema": { "type": "string", "description": "**Market to read.** Optional; defaults to `sa`.\n\n- `sa` — Saudi Arabia (prices in SAR)\n- `jo` — Jordan (prices in JOD)\n\nEach market has its own inventory and its own ids (makes, models, cities, body types, dealers, vehicles). Send only ids from a call made with the same `country`. An id from the other market is answered as an unknown id:\n\n- **404** — a lookup by id: every details route, `/models`, `/finance-providers`, and `category_id` on `/category-news` and `/videos`.\n- **400 naming the param** — `make_id`, `model_id` and `finance_provider_id` on `/new-cars` and `/new-car-filters`; `make_id` and `city_id` on `/dealers`; `make_id` and `company_id` on `/offers`; `make_id`, `author_id` and `category_id` as filters of the news lists, and `make_id` on `/videos` (on `/tag-news`, an unknown `author_id` with a tag that is not a make returns an empty list when the tag has articles in the requested `lang`, and 404 otherwise).\n- **Empty result** — every other id filter, for example `body_type_id`, `fuel_type_id`, `transmission_id` or `origin_id` on `/new-cars`, every `/used-cars` and `/used-car-filters` filter, and `dealer_id` on `/dealers`.", "enum": [ "sa", "jo" ], "default": "sa" }, "required": false, "description": "**Market to read.** Optional; defaults to `sa`.\n\n- `sa` — Saudi Arabia (prices in SAR)\n- `jo` — Jordan (prices in JOD)\n\nEach market has its own inventory and its own ids (makes, models, cities, body types, dealers, vehicles). Send only ids from a call made with the same `country`. An id from the other market is answered as an unknown id:\n\n- **404** — a lookup by id: every details route, `/models`, `/finance-providers`, and `category_id` on `/category-news` and `/videos`.\n- **400 naming the param** — `make_id`, `model_id` and `finance_provider_id` on `/new-cars` and `/new-car-filters`; `make_id` and `city_id` on `/dealers`; `make_id` and `company_id` on `/offers`; `make_id`, `author_id` and `category_id` as filters of the news lists, and `make_id` on `/videos` (on `/tag-news`, an unknown `author_id` with a tag that is not a make returns an empty list when the tag has articles in the requested `lang`, and 404 otherwise).\n- **Empty result** — every other id filter, for example `body_type_id`, `fuel_type_id`, `transmission_id` or `origin_id` on `/new-cars`, every `/used-cars` and `/used-car-filters` filter, and `dealer_id` on `/dealers`.", "name": "country", "in": "query" }, { "schema": { "type": "string", "description": "**Response language.** Optional; defaults to `en`.\n\n- `en` — English\n- `ar` — Arabic\n\nChanges labels, titles and descriptions only; ids and numeric values are the same in both languages.", "enum": [ "en", "ar" ], "default": "en" }, "required": false, "description": "**Response language.** Optional; defaults to `en`.\n\n- `en` — English\n- `ar` — Arabic\n\nChanges labels, titles and descriptions only; ids and numeric values are the same in both languages.", "name": "lang", "in": "query" } ], "responses": { "200": { "description": "**One used-car listing in full.**\n\n- `header` — title, status, year, mileage, gallery, make/model, `share_link`.\n- `price` — price, financing company, VAT and selling companies. `price.price` is `0` when the listing publishes no price (for example \"Contact Seller\").\n- `overview` — labelled specs such as make, model, year, body, fuel, transmission, mileage, colour, city.\n- `description` — text, `vin_number`, grade.\n- `seller` — dealer or private seller with published phone and WhatsApp numbers.\n- `trust` badges and seller-uploaded `inspection_reports` when present.\n- `related_used` (more from this seller), `related_new` and `offers` — shallow lists, each `{title, link, items}` or null.\n\nSections the listing does not have are null (single objects) or empty lists. A sold or expired listing still returns its details with `header.status` showing its state. Unknown ids return 404.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MotorySuccessResponseSchema" }, "example": { "success": true, "data": { "header": { "id": 272443, "status": "active", "tooltip": null, "tooltip_pre_owned": null, "year": 2026, "title": "Nissan X-Trail 2026", "mileage": "0 km", "is_dealer": true, "seller_type": "Dealer", "images": [ "https://s3.eu-central-1.amazonaws.com/v3-cfs.motory.com/vehicle-used/691x518/l-1764172113.3988-6927215161602.webp" ], "images_thumbs": null, "images_full_width": null, "seller_type_url": "https://ksa.motory.com/en/cars-for-sale/?seller_type=1", "video": null, "grade": "", "make_id": 84, "make_logo": "https://s3.eu-central-1.amazonaws.com/v3-common.motory.com/taxonomy/l-1669878674.042-638853920a43c.webp", "make": "Nissan", "make_url": "https://ksa.motory.com/en/cars-for-sale/nissan/", "model_id": 378, "model": "X-Trail", "model_url": "https://ksa.motory.com/en/cars-for-sale/nissan/x-trail/", "year_url": "https://ksa.motory.com/en/cars-for-sale/2026/", "is_featured": true, "package": { "title": "Nitrous Listing", "icon": "https://s3.eu-central-1.amazonaws.com/v3-common.motory.com/common/1710369915.3925-65f22c7b5fd5f.webp", "color": "#5B0DB3" }, "is_pre_owned": false, "is_favorite": false, "request_leads_count": null, "is_vehicle_owner": false, "share_link": "https://ksa.motory.com/en/cars-for-sale/riyadh-haraj/nissan/x-trail/2026/272443/", "reward_data": { "show": false, "type": "default", "currency": "", "prize": "", "text": "", "cashback_code": "", "link_text": "", "action": "", "action_text": "", "action_link": "", "description": "" }, "bread_crumb_urls": null, "is_not_available": false, "not_available_text": null }, "price": { "price": 97175, "financing_information": [], "has_financing": true, "is_motory_shop": false, "motory_shop_icon": null, "motory_shop_link": null, "cell_type": "form_only", "show_financing_info": false, "is_lexus": false, "preferred_financing_company_id": 271, "preferred_financing_company_name": "Syartac", "preferred_financing_company_logo": "https://s3.eu-central-1.amazonaws.com/v3-companies.motory.com/lead-company/l-1726482470.6112-66e80826953a8.webp", "preferred_financing_company_phone": "+966595059649", "preferred_financing_company_cities": [], "preferred_financing_company_periods": [], "lexus_purchase_types_list": [ { "value": "cash", "text": "Cash", "show_component": null, "hide_component": [ "downpayment" ] }, { "value": "finance", "text": "Finance", "show_component": [ "downpayment" ], "hide_component": null } ], "disclaimer": { "title": "Disclaimer", "description": "- Motory is not responsible for any financial transactions between the seller and the buyer, and you will not be required to fill in additional private information using any other links", "description2": "- Before making a purchase, make sure to verify the seller's identity. Also, you should never transfer money in advance", "description3": "- For a safe experience, the financial transactions must be done in person through the official channels" }, "whats_app_disclaimer": { "title": "Disclaimer", "description": "Motory is not responsible for any financial transactions between the seller and the buyer, and you will not be required to fill in additional private information using any other links", "description2": "Before making a purchase, make sure to verify the seller's identity. Also, you should never transfer money in advance", "description3": "For a safe experience, the financial transactions must be done in person through the official channels" }, "call_disclaimer": { "title": "Disclaimer", "description": "Motory is not responsible for any financial transactions between the seller and the buyer, and you will not be required to fill in additional private information using any other links", "description2": "Before making a purchase, make sure to verify the seller's identity. Also, you should never transfer money in advance", "description3": "For a safe experience, the financial transactions must be done in person through the official channels" }, "is_vat_company": false, "is_vat_vehicle": true, "companies": [ { "id": 271, "name": "Syartac", "price": 97175, "is_vat": true, "phone": "+966595059649", "logo": "https://s3.eu-central-1.amazonaws.com/v3-companies.motory.com/lead-company/l-1726482470.6112-66e80826953a8.webp", "small_logo": "https://s3.eu-central-1.amazonaws.com/v3-companies.motory.com/lead-company/l-1726482475.5639-66e8082b89ac5.webp" } ], "vat_text": "VAT Included", "cash_sale_companies": null, "extra_purchase_plan_list": [], "extra_gender_list": [], "extra_model_list": [], "extra_expected_time_to_buy_list": [], "currency": "SR", "per_month": "per month", "price_object": { "hide_price": false, "price_text": "Cash Price with VAT", "price_value": "97,175", "price_currency": "SR", "price_note": "", "monthly_payment": null, "down_payment": null, "final_payment": null, "total_amount": null, "period": 0, "has_financing": true, "finance_text": "Financing", "finance_value": "Available", "disabled_finance_value": false, "disabled_price_value": false, "finance_currency": "", "percentage": null, "show_finance_button": true, "show_cash_button": false, "show_call_button": true }, "request_leads_count": null }, "trust": [ { "title": "Warranty you can count on", "values": "5 Years Warranty", "icon": "https://ksa.motory.com/images/motory_app/guarantee/60-en.png" } ], "overview": [ { "is_image": true, "title": "Make", "text": "Nissan", "image": "https://s3.eu-central-1.amazonaws.com/v3-common.motory.com/taxonomy/l-1669878674.042-638853920a43c.webp", "hex_color": null }, { "is_image": true, "title": "Condition", "text": "New", "image": "https://ksa.motory.com/images/overview_icons/condition.png", "hex_color": null, "tooltip": null }, { "is_image": false, "title": "Color", "text": "Black", "image": null, "hex_color": "#00111C", "hex_color_two": null } ], "description": { "grade": null, "vin_number": null, "description": "New Nissan X-Trail 2026 car for sale with CVT transmission. The mileage when the car is listed for sale is 0. The car also features an exterior color Black. The car is currently located in Riyadh at SAR 97175." }, "seller": { "id": 620813, "name": "Syartac company ", "phone": "+966595059649", "whatsapp_number": "+966565973333", "logo": "https://s3.eu-central-1.amazonaws.com/v3-companies.motory.com/dealer/l-1706970162.88-65be4c32d6d6a.webp", "phone_numbers": [ { "id": 620813, "phone": "+966566972904", "phone_name": "Syartac company customer service" } ], "enable_whatsapp_phone": { "enable_whats_app": true, "enable_phone": true }, "is_dealer": true, "url": "https://ksa.motory.com/en/cars-dealers/riyadh/syartac-company-620813/" }, "inspection_reports": [], "related_used": { "title": "More from this dealer", "link": "https://ksa.motory.com/en/cars-dealers/riyadh/syartac-company-620813/", "items": [ { "vehicle_id": 276772, "vehicle_type": "used", "status": "active", "is_featured": true, "package": { "title": "Nitrous", "icon": "https://s3.eu-central-1.amazonaws.com/v3-common.motory.com/common/1710369915.3925-65f22c7b5fd5f.webp", "color": "#5B0DB3" }, "is_pre_owned": false, "is_favorite": false, "make_logo": "https://s3.eu-central-1.amazonaws.com/v3-common.motory.com/taxonomy/l-1669878687.1593-6388539f26e4e.webp", "make": "MG", "make_id": 50, "model": "3", "model_id": 468, "year": 2025, "title": "MG 3 2025", "url": "https://ksa.motory.com/en/cars-for-sale/riyadh-haraj/mg/3/2025/276772/", "city": "Riyadh", "transmission": "Automatic", "mileage": "0 km", "price_object": { "hide_price": false, "price_text": "Cash Price", "price_value": "39,100", "price_currency": "SR", "price_note": "", "monthly_payment": null, "down_payment": null, "final_payment": null, "total_amount": null, "period": 0, "has_financing": true, "finance_text": "Financing", "finance_value": "Available", "disabled_finance_value": false, "disabled_price_value": false, "finance_currency": "", "percentage": null, "show_finance_button": true, "show_cash_button": false, "show_call_button": true }, "image": "https://s3.eu-central-1.amazonaws.com/v3-cfs.motory.com/vehicle-used/l-1778167131.9072-69fcad5bdd7a6.webp", "images": null, "seller_type": "Dealer", "warranty_text": null } ] }, "offers": { "title": "Nissan Offers", "link": null, "items": [ { "company": { "url": "https://ksa.motory.com/en/cars-offers/manahil-international-nissan-offers/", "name": "Manahil International- Nissan", "image": "https://s3.eu-central-1.amazonaws.com/v3-companies.motory.com/company/50x50/l-1767256617.1412-6956322922794.webp" }, "url": "https://ksa.motory.com/en/cars-offers/altima-2025-zero-down-payment-monthly-installments-from-sar-1260-4809/", "makes_list": [ { "id": 84, "name": "Nissan", "image": "https://s3.eu-central-1.amazonaws.com/v3-common.motory.com/taxonomy/60x60/l-1669878674.042-638853920a43c.webp", "url": "https://ksa.motory.com/en/cars-offers/nissan/", "text": "Nissan", "slug": "nissan" } ], "id": 4809, "title": "Altima 2025 – Zero Down Payment, Monthly Installments from SAR 1260", "offer_begin": "06/10/2026", "offer_end": "31/10/2026", "image": "https://s3.eu-central-1.amazonaws.com/v3-car-offer.motory.com/car-offer/l-1791800211.2558-6accb3933e760.webp", "images": null } ] }, "related_new": { "title": "Nissan New Cars", "link": "https://ksa.motory.com/en/new-cars/nissan/", "items": [ { "vehicle_id": 273391, "vehicle_type": "new", "make_name": "Nissan", "make_id": 84, "model_name": "X-Trail", "model_id": 378, "grade": "2.5 2WD 2ROW S", "title": "Nissan X-Trail 2.5 2WD 2ROW S 2026", "year": 2026, "price": 104999, "is_not_available": false, "is_featured": true, "from_company": true, "price_text": "Asking Price", "monthly_payment": null, "finance_available": true, "company_logo": "https://s3.eu-central-1.amazonaws.com/v3-companies.motory.com/lead-company/92x29/l-1621951411.2492-60ad03b33cd8e.webp", "image": "https://s3.eu-central-1.amazonaws.com/v3-ncg.motory.com/vehicle-new/l-1674464638.6029-63ce4d7e93330_outbound.webp", "images": null, "icon": "https://s3.eu-central-1.amazonaws.com/v3-common.motory.com/taxonomy/l-1669878674.042-638853920a43c.webp", "make_logo": "https://s3.eu-central-1.amazonaws.com/v3-common.motory.com/taxonomy/l-1669878674.042-638853920a43c.webp", "url": "https://ksa.motory.com/en/new-cars/nissan/x-trail/2026/nissan-x-trail-25-2wd-2row-s-2026-273391/", "is_electrical": false, "range_per_charge": null, "fuel_economy": "16.1 Km/L", "engine_capacity": "2.5 L", "horsepower": "181 hp", "price_object": { "hide_price": false, "price_text": "Cash Price", "price_value": "104,999", "price_currency": "SR", "price_note": null, "monthly_payment": null, "down_payment": null, "final_payment": null, "total_amount": null, "period": null, "has_financing": true, "finance_text": "Financing", "finance_value": "Available", "disabled_finance_value": false, "disabled_price_value": false, "finance_currency": "", "percentage": null, "show_finance_button": true, "show_cash_button": true, "show_call_button": false } } ] } } } } } }, "400": { "description": "Bad request — a parameter is missing, malformed or out of range", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MotoryErrorResponseSchema" } } } }, "404": { "description": "Not found — the requested id or link does not exist", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MotoryErrorResponseSchema" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MotoryErrorResponseSchema" } } } }, "503": { "description": "Service busy — retry shortly", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MotoryErrorResponseSchema" } } } } } } }, "/used-cars-by-url": { "get": { "tags": [ "Used Cars" ], "operationId": "searchUsedCarsByUrl", "description": "Run the used-car search that a pasted motory.com search-page link describes (a make, model, city, year or financing page), applying the filters in the link. Takes a url; the returned filters use /used-cars parameter names, and every link parameter that was not applied is listed in ignored_parameters with the reason.", "parameters": [ { "schema": { "type": "string", "description": "**Link to a used-car search page** on ksa.motory.com (Saudi Arabia) or jo.motory.com (Jordan), English or Arabic. Required.\n\nLinks that are read, with their filter parameters (`?transmission_id=…&price_range=50001-75000&sort=-mileage_id`):\n\n- make, model, city and year pages: `/en/cars-for-sale/toyota/camry/`, `/en/cars-for-sale/riyadh-haraj/`, `/en/cars-for-sale/2018/`, Jordan `/en/used-cars/amman/`\n- a make's own page (`/en/toyota/`), read as that make\n- the financing page `/en/cars-for-sale/used-cars-financing/`\n\nOther links:\n\n- A single listing's link, a new-car link or another kind of page → 400 naming the endpoint that takes it, when one does.\n- A link whose make, model or city does not exist, or whose listing id names no live car → 404.\n- An inverted range in the link (`price_range=90000-1000`) → 400, as on `/used-cars`.\n- A link without `/en/` or `/ar/` after the host is answered in Arabic, as the site serves it, unless `lang` is sent.", "example": "https://ksa.motory.com/en/cars-for-sale/riyadh-haraj/kia/?utm_source=newsletter", "maxLength": 2000 }, "required": true, "description": "**Link to a used-car search page** on ksa.motory.com (Saudi Arabia) or jo.motory.com (Jordan), English or Arabic. Required.\n\nLinks that are read, with their filter parameters (`?transmission_id=…&price_range=50001-75000&sort=-mileage_id`):\n\n- make, model, city and year pages: `/en/cars-for-sale/toyota/camry/`, `/en/cars-for-sale/riyadh-haraj/`, `/en/cars-for-sale/2018/`, Jordan `/en/used-cars/amman/`\n- a make's own page (`/en/toyota/`), read as that make\n- the financing page `/en/cars-for-sale/used-cars-financing/`\n\nOther links:\n\n- A single listing's link, a new-car link or another kind of page → 400 naming the endpoint that takes it, when one does.\n- A link whose make, model or city does not exist, or whose listing id names no live car → 404.\n- An inverted range in the link (`price_range=90000-1000`) → 400, as on `/used-cars`.\n- A link without `/en/` or `/ar/` after the host is answered in Arabic, as the site serves it, unless `lang` is sent.", "name": "url", "in": "query" }, { "schema": { "type": "string", "description": "**Response language.** Optional; when omitted, the language of the link itself is used (`/en/` → English, `/ar/` → Arabic, neither → Arabic, as the site serves such a link).\n\n- `en` — English\n- `ar` — Arabic\n\nChanges labels, titles and descriptions only; ids and numeric values are the same in both languages.", "enum": [ "en", "ar" ] }, "required": false, "description": "**Response language.** Optional; when omitted, the language of the link itself is used (`/en/` → English, `/ar/` → Arabic, neither → Arabic, as the site serves such a link).\n\n- `en` — English\n- `ar` — Arabic\n\nChanges labels, titles and descriptions only; ids and numeric values are the same in both languages.", "name": "lang", "in": "query" }, { "schema": { "type": "string", "description": "**Result order**, overriding the link's own order. Optional; when omitted the link's order is used, else `featured`.\n\n- `featured` — promoted listings first\n- `newest` — most recently published first (by publish date, which can differ from the `created_at` date shown on a row)\n- `oldest` — earliest published first (by publish date, which can differ from the `created_at` date shown on a row)\n- `mileage_asc` — lowest mileage band first\n- `mileage_desc` — highest mileage band first\n- `price_asc` — cheapest first\n- `price_desc` — most expensive first\n\nPrice orders follow the same rules as on `/used-cars`: they order the whole result of a search that matches at most 50 listings, listings without a price last, and a larger search returns 400 naming how to narrow it.", "enum": [ "featured", "newest", "oldest", "mileage_asc", "mileage_desc", "price_asc", "price_desc" ] }, "required": false, "description": "**Result order**, overriding the link's own order. Optional; when omitted the link's order is used, else `featured`.\n\n- `featured` — promoted listings first\n- `newest` — most recently published first (by publish date, which can differ from the `created_at` date shown on a row)\n- `oldest` — earliest published first (by publish date, which can differ from the `created_at` date shown on a row)\n- `mileage_asc` — lowest mileage band first\n- `mileage_desc` — highest mileage band first\n- `price_asc` — cheapest first\n- `price_desc` — most expensive first\n\nPrice orders follow the same rules as on `/used-cars`: they order the whole result of a search that matches at most 50 listings, listings without a price last, and a larger search returns 400 naming how to narrow it.", "name": "sort", "in": "query" }, { "schema": { "type": "integer", "description": "**Page number, starting at 1.** Optional; when omitted the link's own page is used, else `1`.\n\nA `page` beyond `pagination.total_pages` returns an empty `items` list.", "minimum": 1, "maximum": 10000 }, "required": false, "description": "**Page number, starting at 1.** Optional; when omitted the link's own page is used, else `1`.\n\nA `page` beyond `pagination.total_pages` returns an empty `items` list.", "name": "page", "in": "query" }, { "schema": { "type": "integer", "description": "**Results per page.** Optional; defaults to `20`, accepts 1–50.\n\nValues above 50 are rejected with 400. Keep the same `page_size` on every page of one search so pages neither overlap nor skip results.", "minimum": 1, "maximum": 50, "default": 20 }, "required": false, "description": "**Results per page.** Optional; defaults to `20`, accepts 1–50.\n\nValues above 50 are rejected with 400. Keep the same `page_size` on every page of one search so pages neither overlap nor skip results.", "name": "page_size", "in": "query" } ], "responses": { "200": { "description": "**Used-car search from a motory.com search-page link.** Paste a make, model, city or year page link (with its filters) and get the same results `/used-cars` gives for those filters.\n\n`filters` echoes what was applied, under `/used-cars` parameter names (plus `sort` when not `featured`), so you can switch to `/used-cars` directly. Link values that take another name or form:\n\n- `price_range=0-0` (or `1-0`), the site's \"with a price\" band → `with_price_only: true`\n- `electric_range=lo-hi` → `min_electric_range` / `max_electric_range` (a top of `0` is open)\n- `dealer=` → `dealer_id`\n- several comma-separated bands, as the site's multi-select filters write them (`price_range=50001-75000,75001-100000`) → one range, when they follow on from each other\n- the financing page's path → `has_financing: true` (and the `pricing` value the page sets)\n\n`ignored_parameters` lists, in link order, every link parameter value that was not applied, as `{name, value, reason}`:\n\n- `not_supported` — a parameter `/used-cars` has no equivalent for (for example `utm_source`, or the site's `monthly_payment` bands: for cars with financing send `has_financing=true` to `/used-cars`), or a selection one minimum/maximum pair cannot hold: years with a gap (`year=2020,2024`) or price / electric-range bands with a gap (`price_range=1-50000,100001-150000`)\n- `invalid_value` — a value that cannot be used (for example `page=abc`, a page above 10000, or a list of more than 50 ids — the most `/used-cars` takes)\n- `no_effect` — a value that filters nothing (for example `has_financing=0`, or `seller_type=1,0` — both seller types ticked)\n- `conflicts_with_path` — the path already fixes this filter (`/toyota/?make_id=71` keeps Toyota)\n- `repeated` — an earlier copy of a parameter given more than once; the last copy is the one applied\n- `overridden` — the link's own `sort` or `page`, replaced by the `sort` / `page` you sent\n\n`items` and `pagination` are exactly as on `/used-cars`. The market comes from the link's host and the language from its `/en/` or `/ar/` segment unless `lang` is sent.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MotorySuccessResponseSchema" }, "example": { "success": true, "data": { "items": [ { "id": 281210, "is_featured": true, "package": { "title": "Nitrous Listing", "icon": "https://s3.eu-central-1.amazonaws.com/v3-common.motory.com/common/1710369915.3925-65f22c7b5fd5f.webp", "color": "#5B0DB3" }, "is_pre_owned": false, "title": "KIA Pegas 2025", "price_object": { "hide_price": false, "price_text": "Selling Price", "price_value": "Contact Seller", "price_currency": "", "price_note": "", "monthly_payment": null, "down_payment": null, "final_payment": null, "total_amount": null, "period": 0, "has_financing": true, "finance_text": "Financing", "finance_value": "Available", "disabled_finance_value": false, "disabled_price_value": false, "finance_currency": "", "percentage": null, "show_finance_button": true, "show_cash_button": false, "show_call_button": true }, "is_favorite": false, "year": 2025, "make_id": 71, "model_id": 266, "status": "active", "make_logo": "https://s3.eu-central-1.amazonaws.com/v3-common.motory.com/taxonomy/l-1669878484.7524-638852d4b7b24.webp", "make": "KIA", "model": "Pegas", "description": "New KIA Pegas 2025 car for sale with Automatic transmission. The mileage when the car is listed for sale is 0. The car also features an exterior color Dark Grey. The car is currently located in Riyadh at SAR 0.", "rejected_reason": null, "created_at": "22/09/2026", "transmission": "Automatic", "mileage": "0 km", "city": "Riyadh", "bread_crumb_urls": null, "has_financing": true, "is_dealer": true, "seller_id": 755077, "seller_name": "Car Empire", "seller_phone": "+966599090002", "phone_numbers": [ { "phone": "+966599090002", "phone_name": "Car Empire" } ], "whatsapp_number": "+966599090002", "enable_whatsapp_phone": { "enable_whats_app": true, "enable_phone": true }, "dealer_type": "Dealer", "dealer_type_url": null, "is_motory_shop": false, "motory_shop_icon": null, "motory_shop_link": null, "show_financing_info": false, "is_lexus": false, "financing_company_id": 334, "financing_company_name": "Car empire ", "financing_company_logo": "https://s3.eu-central-1.amazonaws.com/v3-companies.motory.com/lead-company/l-1766253325.1136-6946e30d1bbd7.webp", "preferred_financing_company_phone": "+966599090002", "preferred_financing_company_cities": [], "preferred_financing_company_periods": [], "down_payment": null, "final_payment": null, "total_amount": null, "percentage": { "down_payment_percentage": null, "monthly_payment_percentage": null, "final_payment_percentage": null }, "period": 0, "lexus_purchase_types_list": [ { "value": "cash", "text": "Cash", "show_component": null, "hide_component": [ "downpayment" ] }, { "value": "finance", "text": "Finance", "show_component": [ "downpayment" ], "hide_component": null } ], "overview_details_4": [ { "is_image": true, "text": "KIA", "image": "https://s3.eu-central-1.amazonaws.com/v3-common.motory.com/taxonomy/l-1669878484.7524-638852d4b7b24.webp" } ], "overview_details_2": [ { "is_image": true, "text": "Sedan", "image": "https://ksa.motory.com/images/overview_icons/body_type.png" } ], "overview": [ { "is_image": true, "text": "KIA", "image": "https://s3.eu-central-1.amazonaws.com/v3-common.motory.com/taxonomy/l-1669878484.7524-638852d4b7b24.webp" } ], "disclaimer": { "title": "Disclaimer", "description": "Motory is not responsible for any financial transactions between the seller and the buyer, and you will not be required to fill in additional private information using any other links", "description2": "Before making a purchase, make sure to verify the seller's identity. Also, you should never transfer money in advance", "description3": "For a safe experience, the financial transactions must be done in person through the official channels" }, "whats_app_disclaimer": { "title": "Disclaimer", "description": "Motory is not responsible for any financial transactions between the seller and the buyer, and you will not be required to fill in additional private information using any other links", "description2": "Before making a purchase, make sure to verify the seller's identity. Also, you should never transfer money in advance", "description3": "For a safe experience, the financial transactions must be done in person through the official channels" }, "call_disclaimer": { "title": "Disclaimer", "description": "Motory is not responsible for any financial transactions between the seller and the buyer, and you will not be required to fill in additional private information using any other links", "description2": "Before making a purchase, make sure to verify the seller's identity. Also, you should never transfer money in advance", "description3": "For a safe experience, the financial transactions must be done in person through the official channels" }, "features": null, "can_edit": true, "images": [ "https://s3.eu-central-1.amazonaws.com/v3-cfs.motory.com/vehicle-used/l-1790084833.0465-6ab286e10b586.webp" ], "images_full": [ "https://s3.eu-central-1.amazonaws.com/v3-cfs.motory.com/vehicle-used/l-1790084833.0465-6ab286e10b586.webp" ], "is_vat_company": false, "is_vat_vehicle": true, "companies": [ { "id": 334, "name": "Car empire ", "price": 0, "is_vat": true, "phone": "+966599090002", "logo": "https://s3.eu-central-1.amazonaws.com/v3-companies.motory.com/lead-company/l-1766253325.1136-6946e30d1bbd7.webp", "small_logo": "https://s3.eu-central-1.amazonaws.com/v3-companies.motory.com/lead-company/l-1766253312.0995-6946e300184d2.webp" } ], "vat_text": "VAT Included", "warranty_text": "3 Years Warranty", "images_count": "1 Pics", "cell_type": "form_only", "cash_sale_companies": [ { "id": 4, "name": "Kia AlJabr", "phone": "+966920014200", "logo": "https://s3.eu-central-1.amazonaws.com/v3-companies.motory.com/company-cash-sale/l-1605479865.9629-5fb1adb9eb14a.webp", "small_logo": "https://s3.eu-central-1.amazonaws.com/v3-companies.motory.com/company-cash-sale/l-1605479866.6855-5fb1adbaa75c6.webp", "cities": [ { "id": 805, "name": "الخرج", "branches": [] }, { "id": 810, "name": "الرياض", "branches": [ { "id": 1282, "name": "Telesales - Central" } ] } ], "extra_fields": { "extra_purchase_plan": false, "extra_gender": false, "extra_model": false, "extra_expected_time_to_buy": true } } ], "extra_purchase_plan_list": [], "extra_gender_list": [], "extra_model_list": [], "extra_expected_time_to_buy_list": [ { "id": 2849, "name": "Immediate" } ], "currency": "SR", "per_month": "per month", "share_link": "https://ksa.motory.com/en/cars-for-sale/riyadh-haraj/kia/pegas/2025/281210/", "url": null, "is_not_available": false, "not_available_text": null } ], "pagination": { "page": 1, "page_size": 20, "total_items": 58, "total_pages": 3 }, "filters": { "make_id": [ 71 ], "city_id": [ 810 ] }, "ignored_parameters": [ { "name": "utm_source", "value": "newsletter", "reason": "not_supported" } ] } } } } }, "400": { "description": "Bad request — a parameter is missing, malformed or out of range", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MotoryErrorResponseSchema" } } } }, "404": { "description": "Not found — the requested id or link does not exist", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MotoryErrorResponseSchema" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MotoryErrorResponseSchema" } } } }, "503": { "description": "Service busy — retry shortly", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MotoryErrorResponseSchema" } } } } } } }, "/used-car-details-by-url": { "get": { "tags": [ "Used Cars" ], "operationId": "getUsedCarDetailsByUrl", "description": "Read a used-car listing in full from its motory.com page link, the same result as /used-car-details without looking up the id first. Takes a url, for example the share_link of a /used-cars row.", "parameters": [ { "schema": { "type": "string", "description": "**Link to one used-car listing page** on ksa.motory.com (Saudi Arabia) or jo.motory.com (Jordan), English or Arabic. Required.\n\nFor example the listing's `share_link`, or a page link copied from a browser: `https://ksa.motory.com/en/cars-for-sale//////`. The market is taken from the host.\n\n- Another kind of link (a new car, a search page, a dealer) → 400 naming the endpoint that takes it, when one does.\n- A listing that no longer exists, or a link whose path does not lead to the listing it names (for example another city) → 404.\n- A link that leads to another listing than the id in its path → 400 naming `/used-car-details` with that listing's `vehicle_id`.\n- A link without `/en/` or `/ar/` after the host is answered in Arabic, as the site serves it, unless `lang` is sent.", "example": "https://ksa.motory.com/en/cars-for-sale/riyadh-haraj/gac/gs3/2026/279921/", "maxLength": 2000 }, "required": true, "description": "**Link to one used-car listing page** on ksa.motory.com (Saudi Arabia) or jo.motory.com (Jordan), English or Arabic. Required.\n\nFor example the listing's `share_link`, or a page link copied from a browser: `https://ksa.motory.com/en/cars-for-sale//////`. The market is taken from the host.\n\n- Another kind of link (a new car, a search page, a dealer) → 400 naming the endpoint that takes it, when one does.\n- A listing that no longer exists, or a link whose path does not lead to the listing it names (for example another city) → 404.\n- A link that leads to another listing than the id in its path → 400 naming `/used-car-details` with that listing's `vehicle_id`.\n- A link without `/en/` or `/ar/` after the host is answered in Arabic, as the site serves it, unless `lang` is sent.", "name": "url", "in": "query" }, { "schema": { "type": "string", "description": "**Response language.** Optional; when omitted, the language of the link itself is used (`/en/` → English, `/ar/` → Arabic, neither → Arabic, as the site serves such a link).\n\n- `en` — English\n- `ar` — Arabic\n\nChanges labels, titles and descriptions only; ids and numeric values are the same in both languages.", "enum": [ "en", "ar" ] }, "required": false, "description": "**Response language.** Optional; when omitted, the language of the link itself is used (`/en/` → English, `/ar/` → Arabic, neither → Arabic, as the site serves such a link).\n\n- `en` — English\n- `ar` — Arabic\n\nChanges labels, titles and descriptions only; ids and numeric values are the same in both languages.", "name": "lang", "in": "query" } ], "responses": { "200": { "description": "**Used-car listing from its motory.com page link.** Same response as `/used-car-details`, without looking up the id first.\n\n- Market: from the link's host (ksa.motory.com → Saudi Arabia, jo.motory.com → Jordan).\n- Language: from the link's `/en/` or `/ar/` segment, unless `lang` is sent.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MotorySuccessResponseSchema" }, "example": { "success": true, "data": { "header": { "id": 279921, "status": "active", "tooltip": null, "tooltip_pre_owned": null, "year": 2026, "title": "GAC GS3 2026", "mileage": "0 km", "is_dealer": true, "seller_type": "Dealer", "images": [ "https://s3.eu-central-1.amazonaws.com/v3-cfs.motory.com/vehicle-used/691x518/l-1786888399.4831-6a81c0cf75f0a.webp" ], "images_thumbs": null, "images_full_width": null, "seller_type_url": "https://ksa.motory.com/en/cars-for-sale/?seller_type=1", "video": null, "grade": "", "make_id": 41, "make_logo": "https://s3.eu-central-1.amazonaws.com/v3-common.motory.com/taxonomy/l-1669880349.8924-63885a1dd9e1f.webp", "make": "GAC", "make_url": "https://ksa.motory.com/en/cars-for-sale/gac/", "model_id": 554, "model": "GS3", "model_url": "https://ksa.motory.com/en/cars-for-sale/gac/gs3/", "year_url": "https://ksa.motory.com/en/cars-for-sale/2026/", "is_featured": false, "package": null, "is_pre_owned": false, "is_favorite": false, "request_leads_count": null, "is_vehicle_owner": false, "share_link": "https://ksa.motory.com/en/cars-for-sale/riyadh-haraj/gac/gs3/2026/279921/", "reward_data": { "show": false, "type": "default", "currency": "", "prize": "", "text": "", "cashback_code": "", "link_text": "", "action": "", "action_text": "", "action_link": "", "description": "" }, "bread_crumb_urls": null, "is_not_available": false, "not_available_text": null }, "price": { "price": 71300, "financing_information": [], "has_financing": true, "is_motory_shop": false, "motory_shop_icon": null, "motory_shop_link": null, "cell_type": "form_only", "show_financing_info": false, "is_lexus": false, "preferred_financing_company_id": 271, "preferred_financing_company_name": "Syartac", "preferred_financing_company_logo": "https://s3.eu-central-1.amazonaws.com/v3-companies.motory.com/lead-company/l-1726482470.6112-66e80826953a8.webp", "preferred_financing_company_phone": "+966595059649", "preferred_financing_company_cities": [], "preferred_financing_company_periods": [], "lexus_purchase_types_list": [ { "value": "cash", "text": "Cash", "show_component": null, "hide_component": [ "downpayment" ] }, { "value": "finance", "text": "Finance", "show_component": [ "downpayment" ], "hide_component": null } ], "disclaimer": { "title": "Disclaimer", "description": "- Motory is not responsible for any financial transactions between the seller and the buyer, and you will not be required to fill in additional private information using any other links", "description2": "- Before making a purchase, make sure to verify the seller's identity. Also, you should never transfer money in advance", "description3": "- For a safe experience, the financial transactions must be done in person through the official channels" }, "whats_app_disclaimer": { "title": "Disclaimer", "description": "Motory is not responsible for any financial transactions between the seller and the buyer, and you will not be required to fill in additional private information using any other links", "description2": "Before making a purchase, make sure to verify the seller's identity. Also, you should never transfer money in advance", "description3": "For a safe experience, the financial transactions must be done in person through the official channels" }, "call_disclaimer": { "title": "Disclaimer", "description": "Motory is not responsible for any financial transactions between the seller and the buyer, and you will not be required to fill in additional private information using any other links", "description2": "Before making a purchase, make sure to verify the seller's identity. Also, you should never transfer money in advance", "description3": "For a safe experience, the financial transactions must be done in person through the official channels" }, "is_vat_company": false, "is_vat_vehicle": true, "companies": [ { "id": 271, "name": "Syartac", "price": 71300, "is_vat": true, "phone": "+966595059649", "logo": "https://s3.eu-central-1.amazonaws.com/v3-companies.motory.com/lead-company/l-1726482470.6112-66e80826953a8.webp", "small_logo": "https://s3.eu-central-1.amazonaws.com/v3-companies.motory.com/lead-company/l-1726482475.5639-66e8082b89ac5.webp" } ], "vat_text": "VAT Included", "cash_sale_companies": null, "extra_purchase_plan_list": [], "extra_gender_list": [], "extra_model_list": [], "extra_expected_time_to_buy_list": [], "currency": "SR", "per_month": "per month", "price_object": { "hide_price": false, "price_text": "Cash Price with VAT", "price_value": "71,300", "price_currency": "SR", "price_note": "", "monthly_payment": null, "down_payment": null, "final_payment": null, "total_amount": null, "period": 0, "has_financing": true, "finance_text": "Financing", "finance_value": "Available", "disabled_finance_value": false, "disabled_price_value": false, "finance_currency": "", "percentage": null, "show_finance_button": true, "show_cash_button": false, "show_call_button": true }, "request_leads_count": null }, "trust": [ { "title": "Warranty you can count on", "values": "6 Years Warranty", "icon": "https://ksa.motory.com/images/motory_app/guarantee/72-en.png" } ], "overview": [ { "is_image": true, "title": "Make", "text": "GAC", "image": "https://s3.eu-central-1.amazonaws.com/v3-common.motory.com/taxonomy/l-1669880349.8924-63885a1dd9e1f.webp", "hex_color": null }, { "is_image": true, "title": "Condition", "text": "New", "image": "https://ksa.motory.com/images/overview_icons/condition.png", "hex_color": null, "tooltip": null }, { "is_image": false, "title": "Color", "text": "Grey", "image": null, "hex_color": "#B3B3B3", "hex_color_two": null } ], "description": { "grade": null, "vin_number": null, "description": "New GAC GS3 2026 car for sale with Automatic transmission. The mileage when the car is listed for sale is 0. The car also features an exterior color Grey. The car is currently located in Riyadh at SAR 71300." }, "seller": { "id": 620813, "name": "Syartac company ", "phone": "+966595059649", "whatsapp_number": "+966565973333", "logo": "https://s3.eu-central-1.amazonaws.com/v3-companies.motory.com/dealer/l-1706970162.88-65be4c32d6d6a.webp", "phone_numbers": [ { "id": 620813, "phone": "+966566972904", "phone_name": "Syartac company customer service" } ], "enable_whatsapp_phone": { "enable_whats_app": true, "enable_phone": true }, "is_dealer": true, "url": "https://ksa.motory.com/en/cars-dealers/riyadh/syartac-company-620813/" }, "inspection_reports": [ { "title": "Car Inspection", "description": "The inspection has been uploaded by the seller", "btn_text": "View Inspection", "logo": "https://ksa.motory.com/images/inspection-report.png", "url": "https://s3.eu-central-1.amazonaws.com/v3-cfs.motory.com/vehicle-used-checking-report/l-1786888390.8534-6a81c0c6d05c7.jpeg" } ], "related_used": { "title": "More from this dealer", "link": "https://ksa.motory.com/en/cars-dealers/riyadh/syartac-company-620813/", "items": [ { "vehicle_id": 276772, "vehicle_type": "used", "status": "active", "is_featured": true, "package": { "title": "Nitrous", "icon": "https://s3.eu-central-1.amazonaws.com/v3-common.motory.com/common/1710369915.3925-65f22c7b5fd5f.webp", "color": "#5B0DB3" }, "is_pre_owned": false, "is_favorite": false, "make_logo": "https://s3.eu-central-1.amazonaws.com/v3-common.motory.com/taxonomy/l-1669878687.1593-6388539f26e4e.webp", "make": "MG", "make_id": 50, "model": "3", "model_id": 468, "year": 2025, "title": "MG 3 2025", "url": "https://ksa.motory.com/en/cars-for-sale/riyadh-haraj/mg/3/2025/276772/", "city": "Riyadh", "transmission": "Automatic", "mileage": "0 km", "price_object": { "hide_price": false, "price_text": "Cash Price", "price_value": "39,100", "price_currency": "SR", "price_note": "", "monthly_payment": null, "down_payment": null, "final_payment": null, "total_amount": null, "period": 0, "has_financing": true, "finance_text": "Financing", "finance_value": "Available", "disabled_finance_value": false, "disabled_price_value": false, "finance_currency": "", "percentage": null, "show_finance_button": true, "show_cash_button": false, "show_call_button": true }, "image": "https://s3.eu-central-1.amazonaws.com/v3-cfs.motory.com/vehicle-used/l-1778167131.9072-69fcad5bdd7a6.webp", "images": null, "seller_type": "Dealer", "warranty_text": null } ] }, "offers": { "title": "GAC Offers", "link": null, "items": [ { "company": { "url": "https://ksa.motory.com/en/cars-offers/watani-auto-offers/", "name": "Watani Auto", "image": "https://s3.eu-central-1.amazonaws.com/v3-companies.motory.com/company/50x50/l-1690786590.9076-64c75b1edd973.webp" }, "url": "https://ksa.motory.com/en/cars-offers/get-your-car-at-watani-auto-with-zero-upfront-cost-4801/", "makes_list": [ { "id": 65, "name": "Hyundai", "image": "https://s3.eu-central-1.amazonaws.com/v3-common.motory.com/taxonomy/60x60/l-1669878510.9276-638852eee2747.webp", "url": "https://ksa.motory.com/en/cars-offers/hyundai/", "text": "Hyundai", "slug": "hyundai" } ], "id": 4801, "title": "Get your car at Watani Auto with zero upfront cost", "offer_begin": "06/10/2026", "offer_end": "31/10/2026", "image": "https://s3.eu-central-1.amazonaws.com/v3-car-offer.motory.com/car-offer/l-1791274415.8173-6ac4adafc78b3.webp", "images": null } ] }, "related_new": { "title": "GAC New Cars", "link": "https://ksa.motory.com/en/new-cars/gac/", "items": [ { "vehicle_id": 267041, "vehicle_type": "new", "make_name": "GAC", "make_id": 41, "model_name": "GS8", "model_id": 551, "grade": "GT 2WD", "title": "GAC GS8 GT 2WD 2026", "year": 2026, "price": 139116, "is_not_available": false, "is_featured": true, "from_company": true, "price_text": "Asking Price", "monthly_payment": null, "finance_available": false, "company_logo": null, "image": "https://s3.eu-central-1.amazonaws.com/v3-ncg.motory.com/vehicle-new/l-1691654044.7071-64d4979caca4e.webp", "images": null, "icon": "https://s3.eu-central-1.amazonaws.com/v3-common.motory.com/taxonomy/l-1669880349.8924-63885a1dd9e1f.webp", "make_logo": "https://s3.eu-central-1.amazonaws.com/v3-common.motory.com/taxonomy/l-1669880349.8924-63885a1dd9e1f.webp", "url": "https://ksa.motory.com/en/new-cars/gac/gs8/2026/gac-gs8-gt-2wd-2026-267041/", "is_electrical": false, "range_per_charge": null, "fuel_economy": "12.4 Km/L", "engine_capacity": "2 L", "horsepower": "200 hp", "price_object": { "hide_price": false, "price_text": "Cash Price", "price_value": "139,116", "price_currency": "SR", "price_note": null, "monthly_payment": null, "down_payment": null, "final_payment": null, "total_amount": null, "period": null, "has_financing": false, "finance_text": null, "finance_value": null, "disabled_finance_value": true, "disabled_price_value": false, "finance_currency": "", "percentage": null, "show_finance_button": false, "show_cash_button": false, "show_call_button": true } } ] } } } } } }, "400": { "description": "Bad request — a parameter is missing, malformed or out of range", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MotoryErrorResponseSchema" } } } }, "404": { "description": "Not found — the requested id or link does not exist", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MotoryErrorResponseSchema" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MotoryErrorResponseSchema" } } } }, "503": { "description": "Service busy — retry shortly", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MotoryErrorResponseSchema" } } } } } } }, "/new-cars": { "get": { "tags": [ "New Cars" ], "operationId": "searchNewCars", "description": "Search the new-car catalogue with prices by make, model, year, price, body, fuel, transmission, origin, electric range, financing and finance provider. Take ids from /makes, /new-car-filters and /finance-providers; open a row's id in /new-car-details.", "parameters": [ { "schema": { "type": "string", "description": "**Market to read.** Optional; defaults to `sa`.\n\n- `sa` — Saudi Arabia (prices in SAR)\n- `jo` — Jordan (prices in JOD)\n\nEach market has its own inventory and its own ids (makes, models, cities, body types, dealers, vehicles). Send only ids from a call made with the same `country`. An id from the other market is answered as an unknown id:\n\n- **404** — a lookup by id: every details route, `/models`, `/finance-providers`, and `category_id` on `/category-news` and `/videos`.\n- **400 naming the param** — `make_id`, `model_id` and `finance_provider_id` on `/new-cars` and `/new-car-filters`; `make_id` and `city_id` on `/dealers`; `make_id` and `company_id` on `/offers`; `make_id`, `author_id` and `category_id` as filters of the news lists, and `make_id` on `/videos` (on `/tag-news`, an unknown `author_id` with a tag that is not a make returns an empty list when the tag has articles in the requested `lang`, and 404 otherwise).\n- **Empty result** — every other id filter, for example `body_type_id`, `fuel_type_id`, `transmission_id` or `origin_id` on `/new-cars`, every `/used-cars` and `/used-car-filters` filter, and `dealer_id` on `/dealers`.", "enum": [ "sa", "jo" ], "default": "sa" }, "required": false, "description": "**Market to read.** Optional; defaults to `sa`.\n\n- `sa` — Saudi Arabia (prices in SAR)\n- `jo` — Jordan (prices in JOD)\n\nEach market has its own inventory and its own ids (makes, models, cities, body types, dealers, vehicles). Send only ids from a call made with the same `country`. An id from the other market is answered as an unknown id:\n\n- **404** — a lookup by id: every details route, `/models`, `/finance-providers`, and `category_id` on `/category-news` and `/videos`.\n- **400 naming the param** — `make_id`, `model_id` and `finance_provider_id` on `/new-cars` and `/new-car-filters`; `make_id` and `city_id` on `/dealers`; `make_id` and `company_id` on `/offers`; `make_id`, `author_id` and `category_id` as filters of the news lists, and `make_id` on `/videos` (on `/tag-news`, an unknown `author_id` with a tag that is not a make returns an empty list when the tag has articles in the requested `lang`, and 404 otherwise).\n- **Empty result** — every other id filter, for example `body_type_id`, `fuel_type_id`, `transmission_id` or `origin_id` on `/new-cars`, every `/used-cars` and `/used-car-filters` filter, and `dealer_id` on `/dealers`.", "name": "country", "in": "query" }, { "schema": { "type": "string", "description": "**Response language.** Optional; defaults to `en`.\n\n- `en` — English\n- `ar` — Arabic\n\nChanges labels, titles and descriptions only; ids and numeric values are the same in both languages.", "enum": [ "en", "ar" ], "default": "en" }, "required": false, "description": "**Response language.** Optional; defaults to `en`.\n\n- `en` — English\n- `ar` — Arabic\n\nChanges labels, titles and descriptions only; ids and numeric values are the same in both languages.", "name": "lang", "in": "query" }, { "schema": { "type": "integer", "description": "**Make filter.** Optional; one make id (for example `90`).\n\nTake ids from `/makes` called with the same `country`. One value only — a comma-separated list is rejected with 400.", "minimum": 1 }, "required": false, "description": "**Make filter.** Optional; one make id (for example `90`).\n\nTake ids from `/makes` called with the same `country`. One value only — a comma-separated list is rejected with 400.", "name": "make_id", "in": "query" }, { "schema": { "type": "integer", "description": "**Model filter.** Optional; one model id.\n\nTake ids from `/models`. Works without `make_id`. One value only — a comma-separated list is rejected with 400.", "minimum": 1 }, "required": false, "description": "**Model filter.** Optional; one model id.\n\nTake ids from `/models`. Works without `make_id`. One value only — a comma-separated list is rejected with 400.", "name": "model_id", "in": "query" }, { "schema": { "type": "integer", "description": "**Earliest model year.** Optional; for example `2025`.\n\nCombine with `max_year` for a range (equal values select one year). `min_year` greater than `max_year` is rejected with 400.\n\nModel years no longer sold:\n\n- When nothing currently sold matches the search, the archived cars that match are listed instead, flagged `is_not_available: true`.\n- That answer is one block of at most 20 cars; `page` and `page_size` page within it.\n- A full block of 20 can be only part of the archived matches, so its `pagination.total_items` and `total_pages` are `null`.\n- Send `model_id` plus a single year to get a complete block.", "minimum": 1900, "maximum": 2100 }, "required": false, "description": "**Earliest model year.** Optional; for example `2025`.\n\nCombine with `max_year` for a range (equal values select one year). `min_year` greater than `max_year` is rejected with 400.\n\nModel years no longer sold:\n\n- When nothing currently sold matches the search, the archived cars that match are listed instead, flagged `is_not_available: true`.\n- That answer is one block of at most 20 cars; `page` and `page_size` page within it.\n- A full block of 20 can be only part of the archived matches, so its `pagination.total_items` and `total_pages` are `null`.\n- Send `model_id` plus a single year to get a complete block.", "name": "min_year", "in": "query" }, { "schema": { "type": "integer", "description": "**Latest model year.** Optional; for example `2026`.\n\nCombine with `min_year` for a range. `max_year` lower than `min_year` is rejected with 400.\n\nModel years no longer sold:\n\n- When nothing currently sold matches the search, the archived cars that match are listed instead, flagged `is_not_available: true`.\n- That answer is one block of at most 20 cars; `page` and `page_size` page within it.\n- A full block of 20 can be only part of the archived matches, so its `pagination.total_items` and `total_pages` are `null`.\n- Send `model_id` plus a single year to get a complete block.", "minimum": 1900, "maximum": 2100 }, "required": false, "description": "**Latest model year.** Optional; for example `2026`.\n\nCombine with `min_year` for a range. `max_year` lower than `min_year` is rejected with 400.\n\nModel years no longer sold:\n\n- When nothing currently sold matches the search, the archived cars that match are listed instead, flagged `is_not_available: true`.\n- That answer is one block of at most 20 cars; `page` and `page_size` page within it.\n- A full block of 20 can be only part of the archived matches, so its `pagination.total_items` and `total_pages` are `null`.\n- Send `model_id` plus a single year to get a complete block.", "name": "max_year", "in": "query" }, { "schema": { "type": "integer", "description": "**Minimum price**, whole number in the market currency (SAR for `sa`, JOD for `jo`). Optional.\n\n`min_price` greater than `max_price` is rejected with 400.", "minimum": 0, "maximum": 100000000 }, "required": false, "description": "**Minimum price**, whole number in the market currency (SAR for `sa`, JOD for `jo`). Optional.\n\n`min_price` greater than `max_price` is rejected with 400.", "name": "min_price", "in": "query" }, { "schema": { "type": "integer", "description": "**Maximum price**, whole number in the market currency (SAR for `sa`, JOD for `jo`). Optional.\n\nSend `max_price` alone for \"up to\", both bounds for a band.", "minimum": 1, "maximum": 100000000 }, "required": false, "description": "**Maximum price**, whole number in the market currency (SAR for `sa`, JOD for `jo`). Optional.\n\nSend `max_price` alone for \"up to\", both bounds for a band.", "name": "max_price", "in": "query" }, { "schema": { "type": "string", "description": "**Body type filter (SUV, Sedan, Hatchback…).** Optional; one or more ids, comma-separated; any listed value matches.\n\nTake ids from `/new-car-filters` (body types) called with the same `country`." }, "required": false, "description": "**Body type filter (SUV, Sedan, Hatchback…).** Optional; one or more ids, comma-separated; any listed value matches.\n\nTake ids from `/new-car-filters` (body types) called with the same `country`.", "name": "body_type_id", "in": "query" }, { "schema": { "type": "string", "description": "**Fuel type filter (Gasoline, Hybrid, Plug-in Hybrid, Electric…).** Optional; one or more ids, comma-separated; any listed value matches.\n\nTake ids from `/new-car-filters` (fuel types) called with the same `country`." }, "required": false, "description": "**Fuel type filter (Gasoline, Hybrid, Plug-in Hybrid, Electric…).** Optional; one or more ids, comma-separated; any listed value matches.\n\nTake ids from `/new-car-filters` (fuel types) called with the same `country`.", "name": "fuel_type_id", "in": "query" }, { "schema": { "type": "string", "description": "**Transmission filter (Automatic, Manual, CVT…).** Optional; one or more ids, comma-separated; any listed value matches.\n\nTake ids from `/new-car-filters` (transmissions) called with the same `country`." }, "required": false, "description": "**Transmission filter (Automatic, Manual, CVT…).** Optional; one or more ids, comma-separated; any listed value matches.\n\nTake ids from `/new-car-filters` (transmissions) called with the same `country`.", "name": "transmission_id", "in": "query" }, { "schema": { "type": "string", "description": "**Manufacturer origin filter (Chinese, Japanese, German, Korean, American…).** Optional; one or more ids, comma-separated; any listed value matches.\n\nTake ids from `/new-car-filters` (origins) called with the same `country`." }, "required": false, "description": "**Manufacturer origin filter (Chinese, Japanese, German, Korean, American…).** Optional; one or more ids, comma-separated; any listed value matches.\n\nTake ids from `/new-car-filters` (origins) called with the same `country`.", "name": "origin_id", "in": "query" }, { "schema": { "type": "boolean", "description": "**Only cars offered with financing.** Optional.\n\n- `true` — keep only cars with financing available\n- omitted — all cars\n\n`false` is rejected with 400: there is no \"without financing\" filter.", "example": "" }, "required": false, "description": "**Only cars offered with financing.** Optional.\n\n- `true` — keep only cars with financing available\n- omitted — all cars\n\n`false` is rejected with 400: there is no \"without financing\" filter.", "name": "has_financing", "in": "query" }, { "schema": { "type": "integer", "description": "**One finance provider's cars only.** Optional; one provider id.\n\nTake `id` from `/finance-providers` called with the same `country`. A row's provider is its `financing_company_id`. An id that is not a provider of this market is rejected with 400.", "minimum": 1 }, "required": false, "description": "**One finance provider's cars only.** Optional; one provider id.\n\nTake `id` from `/finance-providers` called with the same `country`. A row's provider is its `financing_company_id`. An id that is not a provider of this market is rejected with 400.", "name": "finance_provider_id", "in": "query" }, { "schema": { "type": "integer", "description": "**Minimum electric range**, whole kilometres per full charge. Optional.\n\n- Any bound keeps only cars with a published electric range (electric cars, plug-in and range-extender hybrids).\n- Both bounds are inclusive.\n- New-car rows show the range as `range_per_charge` for fully electric cars only; hybrids match on their electric range but show `range_per_charge: null`.\n- `min_electric_range` greater than `max_electric_range` is rejected with 400.", "minimum": 0, "maximum": 10000 }, "required": false, "description": "**Minimum electric range**, whole kilometres per full charge. Optional.\n\n- Any bound keeps only cars with a published electric range (electric cars, plug-in and range-extender hybrids).\n- Both bounds are inclusive.\n- New-car rows show the range as `range_per_charge` for fully electric cars only; hybrids match on their electric range but show `range_per_charge: null`.\n- `min_electric_range` greater than `max_electric_range` is rejected with 400.", "name": "min_electric_range", "in": "query" }, { "schema": { "type": "integer", "description": "**Maximum electric range**, whole kilometres per full charge. Optional.\n\n- Any bound keeps only cars with a published electric range (electric cars, plug-in and range-extender hybrids).\n- Both bounds are inclusive.\n- New-car rows show the range as `range_per_charge` for fully electric cars only; hybrids match on their electric range but show `range_per_charge: null`.\n- Send `max_electric_range` alone for \"up to\", both bounds for a band.", "minimum": 1, "maximum": 10000 }, "required": false, "description": "**Maximum electric range**, whole kilometres per full charge. Optional.\n\n- Any bound keeps only cars with a published electric range (electric cars, plug-in and range-extender hybrids).\n- Both bounds are inclusive.\n- New-car rows show the range as `range_per_charge` for fully electric cars only; hybrids match on their electric range but show `range_per_charge: null`.\n- Send `max_electric_range` alone for \"up to\", both bounds for a band.", "name": "max_electric_range", "in": "query" }, { "schema": { "type": "string", "description": "**Result order.** Optional; defaults to `featured`.\n\n- `featured` — promoted cars first (the marketplace's own order)\n- `year_desc` — newest model year first\n- `year_asc` — oldest model year first\n- `price_asc` — cheapest first\n- `price_desc` — most expensive first", "enum": [ "featured", "year_desc", "year_asc", "price_asc", "price_desc" ], "default": "featured" }, "required": false, "description": "**Result order.** Optional; defaults to `featured`.\n\n- `featured` — promoted cars first (the marketplace's own order)\n- `year_desc` — newest model year first\n- `year_asc` — oldest model year first\n- `price_asc` — cheapest first\n- `price_desc` — most expensive first", "name": "sort", "in": "query" }, { "schema": { "type": "integer", "description": "**Page number, starting at 1.** Optional; defaults to `1`.\n\nKeep `page_size` fixed while paging and stop at `pagination.total_pages`. A `page` beyond the last page returns an empty `items` list.", "minimum": 1, "maximum": 10000, "default": 1 }, "required": false, "description": "**Page number, starting at 1.** Optional; defaults to `1`.\n\nKeep `page_size` fixed while paging and stop at `pagination.total_pages`. A `page` beyond the last page returns an empty `items` list.", "name": "page", "in": "query" }, { "schema": { "type": "integer", "description": "**Results per page.** Optional; defaults to `20`, accepts 1–50.\n\nValues above 50 are rejected with 400. Keep the same `page_size` on every page of one search so pages neither overlap nor skip results.", "minimum": 1, "maximum": 50, "default": 20 }, "required": false, "description": "**Results per page.** Optional; defaults to `20`, accepts 1–50.\n\nValues above 50 are rejected with 400. Keep the same `page_size` on every page of one search so pages neither overlap nor skip results.", "name": "page_size", "in": "query" } ], "responses": { "200": { "description": "**Search the new-car catalogue** (showroom models with their listed prices) in Saudi Arabia or Jordan, with make, model, year, price, body, fuel, transmission, origin, electric range and financing filters, sorted by featured, model year or price.\n\nEach row is a model-year/grade card: title, make/model ids, `price` and `price_object`, engine and economy figures (`range_per_charge` for electric cars), the selling `companies` with their published phone numbers, cash-sale and financing companies, and the public `url`.\n\nArchived model years:\n\n- The list holds the cars currently sold. When nothing currently sold matches the filters, the archived cars that match are listed instead, flagged `is_not_available: true`. This is how older model years are reached (ask for them with `min_year`/`max_year`); a model with no car currently sold returns its old model years even without a year filter.\n- That archived answer is one block of at most 20 cars whatever the `page`, `page_size` or `sort`; `page`/`page_size` page within it.\n- A full block of 20 can be only part of the archived matches (another `sort` can return a different 20), so its `pagination.total_items` and `total_pages` are `null`. Send `model_id` plus a single year to get a complete block.\n\nPaging and related routes:\n\n- `pagination.total_items` counts every match; a `page` past `pagination.total_pages` returns an empty `items` list.\n- Read a row `id` with `/new-car-details` for specs, features, grades and other model years.\n- A dealer's stock is listed by `/used-cars` with `dealer_id`.\n- Ids are per market: send ids obtained with the same `country`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MotorySuccessResponseSchema" }, "example": { "success": true, "data": { "items": [ { "id": 278198, "is_not_available": false, "not_available_text": null, "is_featured": true, "image": "https://s3.eu-central-1.amazonaws.com/v3-ncg.motory.com/vehicle-new/l-1652354792.5079-627ceee87bff3.webp", "images": null, "campaign_badge": null, "title": "Changan Alsvin FULL 2027", "price_object": { "hide_price": false, "price_text": "Cash Price with VAT", "price_value": "48,900", "price_currency": "SR", "price_note": null, "monthly_payment": null, "down_payment": null, "final_payment": null, "total_amount": null, "period": null, "has_financing": true, "finance_text": "Financing", "finance_value": "Available", "disabled_finance_value": false, "disabled_price_value": false, "finance_currency": "", "percentage": null, "show_finance_button": true, "show_cash_button": true, "show_call_button": false }, "make_logo": "https://s3.eu-central-1.amazonaws.com/v3-common.motory.com/taxonomy/l-1669879004.5216-638854dc7f592.webp", "make": "Changan", "make_id": 83, "model": "Alsvin", "model_id": 517, "price": 48900, "is_favorite": false, "has_financing": true, "show_financing_info": false, "financing_company_id": 165, "financing_company_name": "Almajdouie - Changan", "financing_company_logo": "https://s3.eu-central-1.amazonaws.com/v3-companies.motory.com/lead-company/l-1624183522.751-60cf12e2b7597.webp", "is_electrical": false, "engine": null, "range_per_charge": null, "fuel_economy": "14.4 Km/L", "engine_capacity": "1.5 L", "horsepower": "105 hp", "phone": "+966920019992", "year": 2027, "cash_sale": true, "currency": "SR", "per_month": "per month", "companies": [ { "id": 22, "name": "Almajdouie - Changan", "price": 48900, "is_vat": true, "enable_call_dealer": true, "enable_make_inquiry": false, "enable_test_drive": false, "phone": "+966920019992" } ], "cash_sale_companies": [ { "id": 22, "name": "Almajdouie - Changan", "phone": "+966920019992", "logo": "https://s3.eu-central-1.amazonaws.com/v3-companies.motory.com/company-cash-sale/l-1627889871.9199-6107a0cfe0959.webp", "small_logo": "https://s3.eu-central-1.amazonaws.com/v3-companies.motory.com/company-cash-sale/l-1627889869.6628-6107a0cda1d41.webp", "cities": null, "extra_fields": { "extra_purchase_plan": false, "extra_gender": false, "extra_model": false, "extra_expected_time_to_buy": false } } ], "url": "https://ksa.motory.com/en/new-cars/changan/alsvin/2027/changan-alsvin-full-2027-278198/", "cell_type": "form_only" } ], "pagination": { "page": 1, "page_size": 20, "total_items": 1239, "total_pages": 62 } } } } } }, "400": { "description": "Bad request — a parameter is missing, malformed or out of range", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MotoryErrorResponseSchema" } } } }, "404": { "description": "Not found — the requested id or link does not exist", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MotoryErrorResponseSchema" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MotoryErrorResponseSchema" } } } }, "503": { "description": "Service busy — retry shortly", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MotoryErrorResponseSchema" } } } } } } }, "/new-car-details": { "get": { "tags": [ "New Cars" ], "operationId": "getNewCarDetails", "description": "Read one new car (a model year and grade) in full: specs, features, other model years and grades, selling companies with phone numbers, and financing. Takes a vehicle_id, the id of a /new-cars row.", "parameters": [ { "schema": { "type": "integer", "description": "**New car id** (one model year and grade). Required; for example `268052`.\n\nTake `id` from a `/new-cars` row, or an id from `years_grades.years_list` of another new-car detail, fetched with the same `country`. An unknown id, a used-listing id, or an id from the other market returns 404.", "minimum": 1, "example": 268052 }, "required": true, "description": "**New car id** (one model year and grade). Required; for example `268052`.\n\nTake `id` from a `/new-cars` row, or an id from `years_grades.years_list` of another new-car detail, fetched with the same `country`. An unknown id, a used-listing id, or an id from the other market returns 404.", "name": "vehicle_id", "in": "query" }, { "schema": { "type": "string", "description": "**Market to read.** Optional; defaults to `sa`.\n\n- `sa` — Saudi Arabia (prices in SAR)\n- `jo` — Jordan (prices in JOD)\n\nEach market has its own inventory and its own ids (makes, models, cities, body types, dealers, vehicles). Send only ids from a call made with the same `country`. An id from the other market is answered as an unknown id:\n\n- **404** — a lookup by id: every details route, `/models`, `/finance-providers`, and `category_id` on `/category-news` and `/videos`.\n- **400 naming the param** — `make_id`, `model_id` and `finance_provider_id` on `/new-cars` and `/new-car-filters`; `make_id` and `city_id` on `/dealers`; `make_id` and `company_id` on `/offers`; `make_id`, `author_id` and `category_id` as filters of the news lists, and `make_id` on `/videos` (on `/tag-news`, an unknown `author_id` with a tag that is not a make returns an empty list when the tag has articles in the requested `lang`, and 404 otherwise).\n- **Empty result** — every other id filter, for example `body_type_id`, `fuel_type_id`, `transmission_id` or `origin_id` on `/new-cars`, every `/used-cars` and `/used-car-filters` filter, and `dealer_id` on `/dealers`.", "enum": [ "sa", "jo" ], "default": "sa" }, "required": false, "description": "**Market to read.** Optional; defaults to `sa`.\n\n- `sa` — Saudi Arabia (prices in SAR)\n- `jo` — Jordan (prices in JOD)\n\nEach market has its own inventory and its own ids (makes, models, cities, body types, dealers, vehicles). Send only ids from a call made with the same `country`. An id from the other market is answered as an unknown id:\n\n- **404** — a lookup by id: every details route, `/models`, `/finance-providers`, and `category_id` on `/category-news` and `/videos`.\n- **400 naming the param** — `make_id`, `model_id` and `finance_provider_id` on `/new-cars` and `/new-car-filters`; `make_id` and `city_id` on `/dealers`; `make_id` and `company_id` on `/offers`; `make_id`, `author_id` and `category_id` as filters of the news lists, and `make_id` on `/videos` (on `/tag-news`, an unknown `author_id` with a tag that is not a make returns an empty list when the tag has articles in the requested `lang`, and 404 otherwise).\n- **Empty result** — every other id filter, for example `body_type_id`, `fuel_type_id`, `transmission_id` or `origin_id` on `/new-cars`, every `/used-cars` and `/used-car-filters` filter, and `dealer_id` on `/dealers`.", "name": "country", "in": "query" }, { "schema": { "type": "string", "description": "**Response language.** Optional; defaults to `en`.\n\n- `en` — English\n- `ar` — Arabic\n\nChanges labels, titles and descriptions only; ids and numeric values are the same in both languages.", "enum": [ "en", "ar" ], "default": "en" }, "required": false, "description": "**Response language.** Optional; defaults to `en`.\n\n- `en` — English\n- `ar` — Arabic\n\nChanges labels, titles and descriptions only; ids and numeric values are the same in both languages.", "name": "lang", "in": "query" } ], "responses": { "200": { "description": "**One new car (a model year and grade) in full.**\n\n- `header` — title, year, gallery, make/model.\n- `years_grades` — the other model years of this car, each with its own `id`, and grades.\n- `price` — price, financing company with its cities and branches.\n- `overview` — labelled specs such as body, engine, horsepower, fuel economy, transmission, drive.\n- `description`, `features` (feature groups) and `companies` (the selling companies with price and published contact numbers).\n- `related_new`, `related_used` and `offers` — shallow lists, each `{title, link, items}` or null.\n\nSections the car does not have are null (single objects) or empty lists. Unknown ids return 404.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MotorySuccessResponseSchema" }, "example": { "success": true, "data": { "header": { "id": 268052, "status": "active", "year": 2026, "title": "KIA Sonet LX 2026", "images": [ "https://s3.eu-central-1.amazonaws.com/v3-ncg.motory.com/vehicle-new/691x518/l-1727606159.4038-66f92d8f62969_outbound.webp" ], "images_thumbs": null, "campaign_badge": null, "images_full_width": null, "video": "https://cdn.jwplayer.com/videos/1KHJOlNy-46VPhlnS.mp4", "video_thumb": "https://cdn.jwplayer.com/v2/media/1KHJOlNy/poster.jpg?width=1920", "video_type": "jwplayer", "grade": "LX", "make_id": 71, "make_logo": "https://s3.eu-central-1.amazonaws.com/v3-common.motory.com/taxonomy/l-1669878484.7524-638852d4b7b24.webp", "make": "KIA", "model_id": 2482, "model": "Sonet", "is_featured": true, "from_company": true, "is_favorite": false, "share_link": "https://ksa.motory.com/en/new-cars/kia/sonet/2026/kia-sonet-lx-2026-268052/", "compare_link": "https://ksa.motory.com/en/new-cars/compare/kia-sonet-lx-2026-268052/", "request_leads_count": "25+ financing requests last month", "is_not_available": false, "not_available_text": null, "not_available_sub_text": null, "not_available_browse_new_link": null, "not_available_browse_used_link": null, "reward_data": { "show": false, "type": "default", "currency": "", "prize": "", "text": "", "cashback_code": "", "link_text": "", "action": "", "action_text": "", "action_link": "", "description": "" } }, "years_grades": { "year": 2026, "grade": "LX", "years_list": [ { "year": 2026, "id": 268052 } ], "grade_list": [ { "grade": "LX", "id": 268052 } ] }, "price": { "price": 74635, "cell_type": "form_only", "has_financing": true, "show_financing_info": false, "is_lexus": false, "preferred_financing_company_id": 149, "preferred_financing_company_name": "AlJabr - KIA", "preferred_financing_company_logo": "https://s3.eu-central-1.amazonaws.com/v3-companies.motory.com/lead-company/l-1718015728.6059-6666d6f093eb6.webp", "preferred_financing_company_phone": "+966920005772", "preferred_financing_company_cities": [ { "id": 805, "name": "Al Kharj", "branches": [] }, { "id": 810, "name": "Riyadh", "branches": [ { "id": 1228, "text": "Telesales - Central" } ] } ], "preferred_financing_company_periods": [], "lexus_purchase_types_list": [ { "value": "cash", "text": "Cash", "show_component": null, "hide_component": [ "downpayment" ] }, { "value": "finance", "text": "Finance", "show_component": [ "downpayment" ], "hide_component": null } ], "is_vat_company": true, "is_vat_vehicle": true, "vat_text": "VAT Included", "cash_sale_companies": [ { "id": 4, "name": "Kia AlJabr", "phone": "+966920014200", "logo": "https://s3.eu-central-1.amazonaws.com/v3-companies.motory.com/company-cash-sale/l-1605479865.9629-5fb1adb9eb14a.webp", "small_logo": "https://s3.eu-central-1.amazonaws.com/v3-companies.motory.com/company-cash-sale/l-1605479866.6855-5fb1adbaa75c6.webp", "cities": [ { "id": 805, "name": "Al Kharj", "branches": [] }, { "id": 810, "name": "Riyadh", "branches": [ { "id": 1282, "name": "Telesales - Central" } ] } ], "extra_fields": { "extra_purchase_plan": false, "extra_gender": false, "extra_model": false, "extra_expected_time_to_buy": true } } ], "extra_purchase_plan_list": [], "extra_gender_list": [], "extra_model_list": [], "extra_expected_time_to_buy_list": [ { "id": 2849, "name": "Immediate" } ], "currency": "SR", "per_month": "per month", "disclaimer": { "title": "Important Disclaimer Regarding Pricing & Financing", "description": "Retail prices are not inclusive of VAT unless stated otherwise. All of the details provided in this page including the price and monthly payment are indicative, and could change at any moment. Please contact the local dealership or financing provider for more accurate details. Displayed photos are shown for illustration purposes only and might not represent this specific trim/grade.", "description2": null, "description3": null }, "request_leads_count": "25+ financing requests last month", "price_object": { "hide_price": false, "price_text": "Cash Price with VAT", "price_value": "74,635", "price_currency": "SR", "price_note": null, "monthly_payment": null, "down_payment": null, "final_payment": null, "total_amount": null, "period": null, "has_financing": true, "finance_text": "Financing", "finance_value": "Available", "disabled_finance_value": false, "disabled_price_value": false, "finance_currency": "", "percentage": null, "show_finance_button": true, "show_cash_button": true, "show_call_button": false } }, "overview": [ { "is_image": true, "title": "Body Type", "text": "SUV", "image": "https://ksa.motory.com/images/overview_icons/body_type.png", "hex_color": null, "clickable": false, "data": null } ], "description": { "grade": null, "vin_number": null, "description": "New KIA Sonet LX 2026 is a SUV car, featuring a 4 Cylinders engine that runs on Gasoline with a capacity of 1.5 liters, generating a power of 115 horsepower at a consumption rate of 17.3 kilometers per liter. It has a CVT Automatic with FWD. As for entertainment and technology, this car offers a variety of options for features: USB Connection, Bluetooth, Hands-free." }, "features": [ { "title": "Convenience & Comfort", "feature_description": [ "Cruise Control" ] } ], "companies": [ { "id": 4, "name": "Kia AlJabr", "price": 74635, "is_vat": true, "enable_call_dealer": true, "enable_make_inquiry": false, "enable_test_drive": false, "phone": "+966920014200", "whatsapp_number": null, "logo": "https://s3.eu-central-1.amazonaws.com/v3-companies.motory.com/company/l-1746616066.2252-681b3f0236fa2.webp", "enable_whatsapp_phone": { "enable_whats_app": false, "enable_phone": true } } ], "offers": { "title": "KIA Offers", "link": "https://ksa.motory.com/en/cars-offers/kia/", "items": [ { "company": { "url": "https://ksa.motory.com/en/cars-offers/kia-aljabr-offers/", "name": "Kia AlJabr", "image": "https://s3.eu-central-1.amazonaws.com/v3-companies.motory.com/company/50x50/l-1746616066.2252-681b3f0236fa2.webp" }, "url": "https://ksa.motory.com/en/cars-offers/kia-aljabr-maintenance-offers-care-your-car-deserves-4835/", "makes_list": [ { "id": 71, "name": "KIA", "slug": "kia", "url": "https://ksa.motory.com/en/cars-offers/kia/", "image": "https://s3.eu-central-1.amazonaws.com/v3-common.motory.com/taxonomy/l-1669878484.7524-638852d4b7b24.webp" } ], "id": 4835, "title": "Kia Aljabr Maintenance Offers.. Care Your Car Deserves!", "offer_begin": "11/10/2026", "offer_end": "31/10/2026", "image": "https://s3.eu-central-1.amazonaws.com/v3-car-offer.motory.com/car-offer/l-1791715546.6688-6acb68daa3480.webp", "images": null }, { "company": { "url": "https://ksa.motory.com/en/cars-offers/watani-auto-offers/", "name": "Watani Auto", "image": "https://s3.eu-central-1.amazonaws.com/v3-companies.motory.com/company/50x50/l-1690786590.9076-64c75b1edd973.webp" }, "url": "https://ksa.motory.com/en/cars-offers/get-your-car-at-watani-auto-with-zero-upfront-cost-4801/", "makes_list": [ { "id": 65, "name": "Hyundai", "image": "https://s3.eu-central-1.amazonaws.com/v3-common.motory.com/taxonomy/60x60/l-1669878510.9276-638852eee2747.webp", "url": "https://ksa.motory.com/en/cars-offers/hyundai/", "text": "Hyundai", "slug": "hyundai" } ], "id": 4801, "title": "Get your car at Watani Auto with zero upfront cost", "offer_begin": "06/10/2026", "offer_end": "31/10/2026", "image": "https://s3.eu-central-1.amazonaws.com/v3-car-offer.motory.com/car-offer/l-1791274415.8173-6ac4adafc78b3.webp", "images": null } ] }, "related_new": { "title": "Other Grades", "link": null, "items": [ { "vehicle_id": 268053, "vehicle_type": "new", "make_name": "KIA", "make_id": 71, "model_name": "Sonet", "model_id": 2482, "grade": "LX2", "title": "KIA Sonet LX2 2026", "year": 2026, "price": 80385, "is_not_available": false, "is_featured": true, "from_company": true, "price_text": "Asking Price", "monthly_payment": null, "finance_available": true, "company_logo": "https://s3.eu-central-1.amazonaws.com/v3-companies.motory.com/lead-company/92x29/l-1718015728.6059-6666d6f093eb6.webp", "image": "https://s3.eu-central-1.amazonaws.com/v3-ncg.motory.com/vehicle-new/l-1727606268.9434-66f92dfce653d_outbound.webp", "images": null, "icon": "https://s3.eu-central-1.amazonaws.com/v3-common.motory.com/taxonomy/l-1669878484.7524-638852d4b7b24.webp", "make_logo": "https://s3.eu-central-1.amazonaws.com/v3-common.motory.com/taxonomy/l-1669878484.7524-638852d4b7b24.webp", "url": "https://ksa.motory.com/en/new-cars/kia/sonet/2026/kia-sonet-lx2-2026-268053/", "is_electrical": false, "range_per_charge": null, "fuel_economy": "17.3 Km/L", "engine_capacity": "1.5 L", "horsepower": "115 hp", "price_object": { "hide_price": false, "price_text": "Cash Price", "price_value": "80,385", "price_currency": "SR", "price_note": null, "monthly_payment": null, "down_payment": null, "final_payment": null, "total_amount": null, "period": null, "has_financing": true, "finance_text": "Financing", "finance_value": "Available", "disabled_finance_value": false, "disabled_price_value": false, "finance_currency": "", "percentage": null, "show_finance_button": true, "show_cash_button": true, "show_call_button": false } } ] }, "related_used": { "title": "KIA Used Cars", "link": "https://ksa.motory.com/en/cars-for-sale/kia/", "items": [ { "vehicle_id": 278596, "vehicle_type": "used", "status": "active", "is_featured": false, "package": null, "is_pre_owned": false, "is_favorite": false, "make_logo": "https://s3.eu-central-1.amazonaws.com/v3-common.motory.com/taxonomy/l-1669878484.7524-638852d4b7b24.webp", "make": "KIA", "make_id": 71, "model": "Sonet", "model_id": 2482, "year": 2026, "title": "KIA Sonet 2026", "url": "https://ksa.motory.com/en/cars-for-sale/jeddah-haraj/kia/sonet/2026/278596/", "city": "Jeddah", "transmission": "CVT", "mileage": "0 km", "price_object": { "hide_price": false, "price_text": "Cash Price", "price_value": "67,400", "price_currency": "SR", "price_note": "", "monthly_payment": null, "down_payment": null, "final_payment": null, "total_amount": null, "period": 0, "has_financing": true, "finance_text": "Financing", "finance_value": "Available", "disabled_finance_value": false, "disabled_price_value": false, "finance_currency": "", "percentage": null, "show_finance_button": true, "show_cash_button": false, "show_call_button": true }, "image": "https://s3.eu-central-1.amazonaws.com/v3-cfs.motory.com/vehicle-used/l-1783428625.6245-6a4cf61198757.webp", "images": null, "seller_type": "Dealer", "warranty_text": null } ] } } } } } }, "400": { "description": "Bad request — a parameter is missing, malformed or out of range", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MotoryErrorResponseSchema" } } } }, "404": { "description": "Not found — the requested id or link does not exist", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MotoryErrorResponseSchema" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MotoryErrorResponseSchema" } } } }, "503": { "description": "Service busy — retry shortly", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MotoryErrorResponseSchema" } } } } } } }, "/new-cars-by-url": { "get": { "tags": [ "New Cars" ], "operationId": "searchNewCarsByUrl", "description": "Run the new-car search that a pasted motory.com search-page link describes (a make, model, year or financing page), applying the filters in the link. The returned filters use /new-cars parameter names, and every link parameter that was not applied is listed in ignored_parameters with the reason.", "parameters": [ { "schema": { "type": "string", "description": "**Link to a new-car search page** on ksa.motory.com (Saudi Arabia) or jo.motory.com (Jordan), English or Arabic. Required.\n\nLinks that are read, with their filter parameters (`?body_type_id=…&price_range=100001-150000&sort=-price`):\n\n- make, model and year pages: `/en/new-cars/toyota/`, `/en/new-cars/toyota/camry/2026/`, `/en/new-cars/toyota/2027/`, `/en/new-cars/2027/`\n- a make's own page (`/en/toyota/`), read as that make\n- financing pages: `/en/new-cars/new-cars-financing/`, `/en/new-cars/toyota/new-cars-financing/`\n\nOther links:\n\n- A single car's link, a used-car link or another kind of page → 400 naming the endpoint that takes it, when one does.\n- A link whose make or model does not exist, or whose car id names no live car → 404.\n- An inverted range in the link (`price_range=90000-1000`) → 400, as on `/new-cars`.\n- A link without `/en/` or `/ar/` after the host is answered in Arabic, as the site serves it, unless `lang` is sent.", "example": "https://ksa.motory.com/en/new-cars/toyota/camry/?utm_source=newsletter", "maxLength": 2000 }, "required": true, "description": "**Link to a new-car search page** on ksa.motory.com (Saudi Arabia) or jo.motory.com (Jordan), English or Arabic. Required.\n\nLinks that are read, with their filter parameters (`?body_type_id=…&price_range=100001-150000&sort=-price`):\n\n- make, model and year pages: `/en/new-cars/toyota/`, `/en/new-cars/toyota/camry/2026/`, `/en/new-cars/toyota/2027/`, `/en/new-cars/2027/`\n- a make's own page (`/en/toyota/`), read as that make\n- financing pages: `/en/new-cars/new-cars-financing/`, `/en/new-cars/toyota/new-cars-financing/`\n\nOther links:\n\n- A single car's link, a used-car link or another kind of page → 400 naming the endpoint that takes it, when one does.\n- A link whose make or model does not exist, or whose car id names no live car → 404.\n- An inverted range in the link (`price_range=90000-1000`) → 400, as on `/new-cars`.\n- A link without `/en/` or `/ar/` after the host is answered in Arabic, as the site serves it, unless `lang` is sent.", "name": "url", "in": "query" }, { "schema": { "type": "string", "description": "**Response language.** Optional; when omitted, the language of the link itself is used (`/en/` → English, `/ar/` → Arabic, neither → Arabic, as the site serves such a link).\n\n- `en` — English\n- `ar` — Arabic\n\nChanges labels, titles and descriptions only; ids and numeric values are the same in both languages.", "enum": [ "en", "ar" ] }, "required": false, "description": "**Response language.** Optional; when omitted, the language of the link itself is used (`/en/` → English, `/ar/` → Arabic, neither → Arabic, as the site serves such a link).\n\n- `en` — English\n- `ar` — Arabic\n\nChanges labels, titles and descriptions only; ids and numeric values are the same in both languages.", "name": "lang", "in": "query" }, { "schema": { "type": "string", "description": "**Result order**, overriding the link's own order. Optional; when omitted the link's order is used, else `featured`.\n\n- `featured` — promoted cars first\n- `year_desc` — newest model year first\n- `year_asc` — oldest model year first\n- `price_asc` — cheapest first\n- `price_desc` — most expensive first", "enum": [ "featured", "year_desc", "year_asc", "price_asc", "price_desc" ] }, "required": false, "description": "**Result order**, overriding the link's own order. Optional; when omitted the link's order is used, else `featured`.\n\n- `featured` — promoted cars first\n- `year_desc` — newest model year first\n- `year_asc` — oldest model year first\n- `price_asc` — cheapest first\n- `price_desc` — most expensive first", "name": "sort", "in": "query" }, { "schema": { "type": "integer", "description": "**Page number, starting at 1.** Optional; when omitted the link's own page is used, else `1`.\n\nA `page` beyond `pagination.total_pages` returns an empty `items` list.", "minimum": 1, "maximum": 10000 }, "required": false, "description": "**Page number, starting at 1.** Optional; when omitted the link's own page is used, else `1`.\n\nA `page` beyond `pagination.total_pages` returns an empty `items` list.", "name": "page", "in": "query" }, { "schema": { "type": "integer", "description": "**Results per page.** Optional; defaults to `20`, accepts 1–50.\n\nValues above 50 are rejected with 400. Keep the same `page_size` on every page of one search so pages neither overlap nor skip results.", "minimum": 1, "maximum": 50, "default": 20 }, "required": false, "description": "**Results per page.** Optional; defaults to `20`, accepts 1–50.\n\nValues above 50 are rejected with 400. Keep the same `page_size` on every page of one search so pages neither overlap nor skip results.", "name": "page_size", "in": "query" } ], "responses": { "200": { "description": "**New-car search from a motory.com search-page link.** Paste a make, model or year page link (with its filters) and get the same results `/new-cars` gives for those filters.\n\n`filters` echoes what was applied, under `/new-cars` parameter names (plus `sort` when not `featured`), so you can switch to `/new-cars` directly. Link values that take another name or form:\n\n- `electric_range=lo-hi` → `min_electric_range` / `max_electric_range` (a top of `0` is open)\n- several comma-separated bands, as the site's multi-select filters write them (`electric_range=301-400,401-500`) → one range, when they follow on from each other\n- a financing page's path → `has_financing: true`\n\n`ignored_parameters` lists, in link order, every link parameter value that was not applied, as `{name, value, reason}`:\n\n- `not_supported` — a parameter `/new-cars` has no equivalent for (for example `utm_source`, or the site's `monthly_payment` bands: for cars with financing send `has_financing=true` to `/new-cars`), or a selection one minimum/maximum pair cannot hold: years with a gap (`year=2020,2024`) or price / electric-range bands with a gap (`price_range=100001-150000,200001-250000`)\n- `invalid_value` — a value that cannot be used (for example a second make in `make_id=90,71`, since `/new-cars` takes one, `page=abc`, or a list of more than 50 ids — the most `/new-cars` takes)\n- `no_effect` — a value that filters nothing (for example `price_range=0-0`, which every new car matches, or `has_financing=0`)\n- `conflicts_with_path` — the path already fixes this filter (`/toyota/?make_id=71` keeps Toyota)\n- `repeated` — an earlier copy of a parameter given more than once; the last copy is the one applied\n- `overridden` — the link's own `sort` or `page`, replaced by the `sort` / `page` you sent\n\n`items` and `pagination` are exactly as on `/new-cars`, including the archived older model years a year page can list. The market comes from the link's host and the language from its `/en/` or `/ar/` segment unless `lang` is sent.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MotorySuccessResponseSchema" }, "example": { "success": true, "data": { "items": [ { "id": 276697, "is_not_available": false, "not_available_text": null, "is_featured": true, "image": "https://s3.eu-central-1.amazonaws.com/v3-ncg.motory.com/vehicle-new/l-1724050706.4308-66c2ed12692f7.webp", "images": null, "campaign_badge": null, "title": "Toyota Camry E 2026", "price_object": { "hide_price": false, "price_text": "Cash Price with VAT", "price_value": "109,825", "price_currency": "SR", "price_note": null, "monthly_payment": null, "down_payment": null, "final_payment": null, "total_amount": null, "period": null, "has_financing": true, "finance_text": "Financing", "finance_value": "Available", "disabled_finance_value": false, "disabled_price_value": false, "finance_currency": "", "percentage": null, "show_finance_button": true, "show_cash_button": true, "show_call_button": false }, "make_logo": "https://s3.eu-central-1.amazonaws.com/v3-common.motory.com/taxonomy/l-1669878465.8496-638852c1cf6f3.webp", "make": "Toyota", "make_id": 90, "model": "Camry", "model_id": 429, "price": 109825, "is_favorite": false, "has_financing": true, "show_financing_info": false, "financing_company_id": 150, "financing_company_name": "ALJRe - Toyota", "financing_company_logo": "https://s3.eu-central-1.amazonaws.com/v3-companies.motory.com/lead-company/l-1638792551.1995-61adfd6730b27.webp", "is_electrical": false, "engine": null, "range_per_charge": null, "fuel_economy": "17.2 Km/L", "engine_capacity": "2.5 L", "horsepower": "201 hp", "phone": "+9668004400055", "year": 2026, "cash_sale": true, "currency": "SR", "per_month": "per month", "companies": [ { "id": 1, "name": "Abdul Latif Jameel Motors - Toyota", "price": 109825, "is_vat": true, "enable_call_dealer": true, "enable_make_inquiry": false, "enable_test_drive": false, "phone": "+9668004400055" } ], "cash_sale_companies": [ { "id": 1, "name": "Abdul Latif Jameel Motors - Toyota", "phone": "+966920024454", "logo": "https://s3.eu-central-1.amazonaws.com/v3-companies.motory.com/company-cash-sale/l-1605479919.9596-5fb1adefea489.webp", "small_logo": "https://s3.eu-central-1.amazonaws.com/v3-companies.motory.com/company-cash-sale/l-1605479920.7501-5fb1adf0b7232.webp", "cities": null, "extra_fields": { "extra_purchase_plan": false, "extra_gender": false, "extra_model": false, "extra_expected_time_to_buy": false } } ], "url": "https://ksa.motory.com/en/new-cars/toyota/camry/2026/toyota-camry-e-2026-276697/", "cell_type": "form_only" } ], "pagination": { "page": 1, "page_size": 20, "total_items": 13, "total_pages": 1 }, "filters": { "make_id": 90, "model_id": 429 }, "ignored_parameters": [ { "name": "utm_source", "value": "newsletter", "reason": "not_supported" } ] } } } } }, "400": { "description": "Bad request — a parameter is missing, malformed or out of range", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MotoryErrorResponseSchema" } } } }, "404": { "description": "Not found — the requested id or link does not exist", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MotoryErrorResponseSchema" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MotoryErrorResponseSchema" } } } }, "503": { "description": "Service busy — retry shortly", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MotoryErrorResponseSchema" } } } } } } }, "/new-car-details-by-url": { "get": { "tags": [ "New Cars" ], "operationId": "getNewCarDetailsByUrl", "description": "Read a new car in full from its motory.com page link, the same result as /new-car-details without looking up the id first. Takes a url of one new-car page, for example the url of a /new-cars row.", "parameters": [ { "schema": { "type": "string", "description": "**Link to one new-car page** on ksa.motory.com (Saudi Arabia) or jo.motory.com (Jordan), English or Arabic. Required.\n\nFor example a new-car row's `url`, or a page link copied from a browser: `https://ksa.motory.com/en/new-cars////-/`. The market is taken from the host. Pages of older model years no longer sold work too.\n\n- Another kind of link (a used car, a search page, a dealer) → 400 naming the endpoint that takes it, when one does.\n- An unknown car, or a link whose path does not lead to the car it names (for example a grade slug without its trailing id) → 404.\n- A link that leads to another car than the id in its path → 400 naming `/new-car-details` with that car's `vehicle_id`.\n- A link without `/en/` or `/ar/` after the host is answered in Arabic, as the site serves it, unless `lang` is sent.", "example": "https://ksa.motory.com/en/new-cars/kia/sonet/2026/kia-sonet-lx-2026-268052/", "maxLength": 2000 }, "required": true, "description": "**Link to one new-car page** on ksa.motory.com (Saudi Arabia) or jo.motory.com (Jordan), English or Arabic. Required.\n\nFor example a new-car row's `url`, or a page link copied from a browser: `https://ksa.motory.com/en/new-cars////-/`. The market is taken from the host. Pages of older model years no longer sold work too.\n\n- Another kind of link (a used car, a search page, a dealer) → 400 naming the endpoint that takes it, when one does.\n- An unknown car, or a link whose path does not lead to the car it names (for example a grade slug without its trailing id) → 404.\n- A link that leads to another car than the id in its path → 400 naming `/new-car-details` with that car's `vehicle_id`.\n- A link without `/en/` or `/ar/` after the host is answered in Arabic, as the site serves it, unless `lang` is sent.", "name": "url", "in": "query" }, { "schema": { "type": "string", "description": "**Response language.** Optional; when omitted, the language of the link itself is used (`/en/` → English, `/ar/` → Arabic, neither → Arabic, as the site serves such a link).\n\n- `en` — English\n- `ar` — Arabic\n\nChanges labels, titles and descriptions only; ids and numeric values are the same in both languages.", "enum": [ "en", "ar" ] }, "required": false, "description": "**Response language.** Optional; when omitted, the language of the link itself is used (`/en/` → English, `/ar/` → Arabic, neither → Arabic, as the site serves such a link).\n\n- `en` — English\n- `ar` — Arabic\n\nChanges labels, titles and descriptions only; ids and numeric values are the same in both languages.", "name": "lang", "in": "query" } ], "responses": { "200": { "description": "**New car (model year and grade) from its motory.com page link.** Same response as `/new-car-details`, without looking up the id first.\n\n- Market: from the link's host (ksa.motory.com → Saudi Arabia, jo.motory.com → Jordan).\n- Language: from the link's `/en/` or `/ar/` segment, unless `lang` is sent.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MotorySuccessResponseSchema" }, "example": { "success": true, "data": { "header": { "id": 268052, "status": "active", "year": 2026, "title": "KIA Sonet LX 2026", "images": [ "https://s3.eu-central-1.amazonaws.com/v3-ncg.motory.com/vehicle-new/691x518/l-1727606159.4038-66f92d8f62969_outbound.webp" ], "images_thumbs": null, "campaign_badge": null, "images_full_width": null, "video": "https://cdn.jwplayer.com/videos/1KHJOlNy-46VPhlnS.mp4", "video_thumb": "https://cdn.jwplayer.com/v2/media/1KHJOlNy/poster.jpg?width=1920", "video_type": "jwplayer", "grade": "LX", "make_id": 71, "make_logo": "https://s3.eu-central-1.amazonaws.com/v3-common.motory.com/taxonomy/l-1669878484.7524-638852d4b7b24.webp", "make": "KIA", "model_id": 2482, "model": "Sonet", "is_featured": true, "from_company": true, "is_favorite": false, "share_link": "https://ksa.motory.com/en/new-cars/kia/sonet/2026/kia-sonet-lx-2026-268052/", "compare_link": "https://ksa.motory.com/en/new-cars/compare/kia-sonet-lx-2026-268052/", "request_leads_count": "25+ financing requests last month", "is_not_available": false, "not_available_text": null, "not_available_sub_text": null, "not_available_browse_new_link": null, "not_available_browse_used_link": null, "reward_data": { "show": false, "type": "default", "currency": "", "prize": "", "text": "", "cashback_code": "", "link_text": "", "action": "", "action_text": "", "action_link": "", "description": "" } }, "years_grades": { "year": 2026, "grade": "LX", "years_list": [ { "year": 2026, "id": 268052 } ], "grade_list": [ { "grade": "LX", "id": 268052 } ] }, "price": { "price": 74635, "cell_type": "form_only", "has_financing": true, "show_financing_info": false, "is_lexus": false, "preferred_financing_company_id": 149, "preferred_financing_company_name": "AlJabr - KIA", "preferred_financing_company_logo": "https://s3.eu-central-1.amazonaws.com/v3-companies.motory.com/lead-company/l-1718015728.6059-6666d6f093eb6.webp", "preferred_financing_company_phone": "+966920005772", "preferred_financing_company_cities": [ { "id": 805, "name": "Al Kharj", "branches": [] }, { "id": 810, "name": "Riyadh", "branches": [ { "id": 1228, "text": "Telesales - Central" } ] } ], "preferred_financing_company_periods": [], "lexus_purchase_types_list": [ { "value": "cash", "text": "Cash", "show_component": null, "hide_component": [ "downpayment" ] }, { "value": "finance", "text": "Finance", "show_component": [ "downpayment" ], "hide_component": null } ], "is_vat_company": true, "is_vat_vehicle": true, "vat_text": "VAT Included", "cash_sale_companies": [ { "id": 4, "name": "Kia AlJabr", "phone": "+966920014200", "logo": "https://s3.eu-central-1.amazonaws.com/v3-companies.motory.com/company-cash-sale/l-1605479865.9629-5fb1adb9eb14a.webp", "small_logo": "https://s3.eu-central-1.amazonaws.com/v3-companies.motory.com/company-cash-sale/l-1605479866.6855-5fb1adbaa75c6.webp", "cities": [ { "id": 805, "name": "Al Kharj", "branches": [] }, { "id": 810, "name": "Riyadh", "branches": [ { "id": 1282, "name": "Telesales - Central" } ] } ], "extra_fields": { "extra_purchase_plan": false, "extra_gender": false, "extra_model": false, "extra_expected_time_to_buy": true } } ], "extra_purchase_plan_list": [], "extra_gender_list": [], "extra_model_list": [], "extra_expected_time_to_buy_list": [ { "id": 2849, "name": "Immediate" } ], "currency": "SR", "per_month": "per month", "disclaimer": { "title": "Important Disclaimer Regarding Pricing & Financing", "description": "Retail prices are not inclusive of VAT unless stated otherwise. All of the details provided in this page including the price and monthly payment are indicative, and could change at any moment. Please contact the local dealership or financing provider for more accurate details. Displayed photos are shown for illustration purposes only and might not represent this specific trim/grade.", "description2": null, "description3": null }, "request_leads_count": "25+ financing requests last month", "price_object": { "hide_price": false, "price_text": "Cash Price with VAT", "price_value": "74,635", "price_currency": "SR", "price_note": null, "monthly_payment": null, "down_payment": null, "final_payment": null, "total_amount": null, "period": null, "has_financing": true, "finance_text": "Financing", "finance_value": "Available", "disabled_finance_value": false, "disabled_price_value": false, "finance_currency": "", "percentage": null, "show_finance_button": true, "show_cash_button": true, "show_call_button": false } }, "overview": [ { "is_image": true, "title": "Body Type", "text": "SUV", "image": "https://ksa.motory.com/images/overview_icons/body_type.png", "hex_color": null, "clickable": false, "data": null } ], "description": { "grade": null, "vin_number": null, "description": "New KIA Sonet LX 2026 is a SUV car, featuring a 4 Cylinders engine that runs on Gasoline with a capacity of 1.5 liters, generating a power of 115 horsepower at a consumption rate of 17.3 kilometers per liter. It has a CVT Automatic with FWD. As for entertainment and technology, this car offers a variety of options for features: USB Connection, Bluetooth, Hands-free." }, "features": [ { "title": "Convenience & Comfort", "feature_description": [ "Cruise Control" ] } ], "companies": [ { "id": 4, "name": "Kia AlJabr", "price": 74635, "is_vat": true, "enable_call_dealer": true, "enable_make_inquiry": false, "enable_test_drive": false, "phone": "+966920014200", "whatsapp_number": null, "logo": "https://s3.eu-central-1.amazonaws.com/v3-companies.motory.com/company/l-1746616066.2252-681b3f0236fa2.webp", "enable_whatsapp_phone": { "enable_whats_app": false, "enable_phone": true } } ], "offers": { "title": "KIA Offers", "link": "https://ksa.motory.com/en/cars-offers/kia/", "items": [ { "company": { "url": "https://ksa.motory.com/en/cars-offers/kia-aljabr-offers/", "name": "Kia AlJabr", "image": "https://s3.eu-central-1.amazonaws.com/v3-companies.motory.com/company/50x50/l-1746616066.2252-681b3f0236fa2.webp" }, "url": "https://ksa.motory.com/en/cars-offers/kia-aljabr-maintenance-offers-care-your-car-deserves-4835/", "makes_list": [ { "id": 71, "name": "KIA", "slug": "kia", "url": "https://ksa.motory.com/en/cars-offers/kia/", "image": "https://s3.eu-central-1.amazonaws.com/v3-common.motory.com/taxonomy/l-1669878484.7524-638852d4b7b24.webp" } ], "id": 4835, "title": "Kia Aljabr Maintenance Offers.. Care Your Car Deserves!", "offer_begin": "11/10/2026", "offer_end": "31/10/2026", "image": "https://s3.eu-central-1.amazonaws.com/v3-car-offer.motory.com/car-offer/l-1791715546.6688-6acb68daa3480.webp", "images": null }, { "company": { "url": "https://ksa.motory.com/en/cars-offers/watani-auto-offers/", "name": "Watani Auto", "image": "https://s3.eu-central-1.amazonaws.com/v3-companies.motory.com/company/50x50/l-1690786590.9076-64c75b1edd973.webp" }, "url": "https://ksa.motory.com/en/cars-offers/get-your-car-at-watani-auto-with-zero-upfront-cost-4801/", "makes_list": [ { "id": 65, "name": "Hyundai", "image": "https://s3.eu-central-1.amazonaws.com/v3-common.motory.com/taxonomy/60x60/l-1669878510.9276-638852eee2747.webp", "url": "https://ksa.motory.com/en/cars-offers/hyundai/", "text": "Hyundai", "slug": "hyundai" } ], "id": 4801, "title": "Get your car at Watani Auto with zero upfront cost", "offer_begin": "06/10/2026", "offer_end": "31/10/2026", "image": "https://s3.eu-central-1.amazonaws.com/v3-car-offer.motory.com/car-offer/l-1791274415.8173-6ac4adafc78b3.webp", "images": null } ] }, "related_new": { "title": "Other Grades", "link": null, "items": [ { "vehicle_id": 268053, "vehicle_type": "new", "make_name": "KIA", "make_id": 71, "model_name": "Sonet", "model_id": 2482, "grade": "LX2", "title": "KIA Sonet LX2 2026", "year": 2026, "price": 80385, "is_not_available": false, "is_featured": true, "from_company": true, "price_text": "Asking Price", "monthly_payment": null, "finance_available": true, "company_logo": "https://s3.eu-central-1.amazonaws.com/v3-companies.motory.com/lead-company/92x29/l-1718015728.6059-6666d6f093eb6.webp", "image": "https://s3.eu-central-1.amazonaws.com/v3-ncg.motory.com/vehicle-new/l-1727606268.9434-66f92dfce653d_outbound.webp", "images": null, "icon": "https://s3.eu-central-1.amazonaws.com/v3-common.motory.com/taxonomy/l-1669878484.7524-638852d4b7b24.webp", "make_logo": "https://s3.eu-central-1.amazonaws.com/v3-common.motory.com/taxonomy/l-1669878484.7524-638852d4b7b24.webp", "url": "https://ksa.motory.com/en/new-cars/kia/sonet/2026/kia-sonet-lx2-2026-268053/", "is_electrical": false, "range_per_charge": null, "fuel_economy": "17.3 Km/L", "engine_capacity": "1.5 L", "horsepower": "115 hp", "price_object": { "hide_price": false, "price_text": "Cash Price", "price_value": "80,385", "price_currency": "SR", "price_note": null, "monthly_payment": null, "down_payment": null, "final_payment": null, "total_amount": null, "period": null, "has_financing": true, "finance_text": "Financing", "finance_value": "Available", "disabled_finance_value": false, "disabled_price_value": false, "finance_currency": "", "percentage": null, "show_finance_button": true, "show_cash_button": true, "show_call_button": false } } ] }, "related_used": { "title": "KIA Used Cars", "link": "https://ksa.motory.com/en/cars-for-sale/kia/", "items": [ { "vehicle_id": 278596, "vehicle_type": "used", "status": "active", "is_featured": false, "package": null, "is_pre_owned": false, "is_favorite": false, "make_logo": "https://s3.eu-central-1.amazonaws.com/v3-common.motory.com/taxonomy/l-1669878484.7524-638852d4b7b24.webp", "make": "KIA", "make_id": 71, "model": "Sonet", "model_id": 2482, "year": 2026, "title": "KIA Sonet 2026", "url": "https://ksa.motory.com/en/cars-for-sale/jeddah-haraj/kia/sonet/2026/278596/", "city": "Jeddah", "transmission": "CVT", "mileage": "0 km", "price_object": { "hide_price": false, "price_text": "Cash Price", "price_value": "67,400", "price_currency": "SR", "price_note": "", "monthly_payment": null, "down_payment": null, "final_payment": null, "total_amount": null, "period": 0, "has_financing": true, "finance_text": "Financing", "finance_value": "Available", "disabled_finance_value": false, "disabled_price_value": false, "finance_currency": "", "percentage": null, "show_finance_button": true, "show_cash_button": false, "show_call_button": true }, "image": "https://s3.eu-central-1.amazonaws.com/v3-cfs.motory.com/vehicle-used/l-1783428625.6245-6a4cf61198757.webp", "images": null, "seller_type": "Dealer", "warranty_text": null } ] } } } } } }, "400": { "description": "Bad request — a parameter is missing, malformed or out of range", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MotoryErrorResponseSchema" } } } }, "404": { "description": "Not found — the requested id or link does not exist", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MotoryErrorResponseSchema" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MotoryErrorResponseSchema" } } } }, "503": { "description": "Service busy — retry shortly", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MotoryErrorResponseSchema" } } } } } } }, "/compare-new-cars": { "get": { "tags": [ "New Cars" ], "operationId": "compareNewCars", "description": "Compare two new cars side by side: prices and spec-by-spec rows by category, plus similar comparisons. Takes two new-car ids (vehicle_id_1, vehicle_id_2) from /new-cars rows or /compare-suggestions.", "parameters": [ { "schema": { "type": "integer", "description": "**First new car to compare.** Required; for example `278198` (Saudi Arabia).\n\nA new-car id (one model year and grade): take `id` from a `/new-cars` row, an id from `years_grades.years_list` of /new-car-details, or a `vehicle_id` from /compare-suggestions, fetched with the same `country`. Older model years work too. Must differ from the other car; an unknown id, a used-listing id or an id from the other market returns 404 naming this parameter.", "minimum": 1, "example": 278198 }, "required": true, "description": "**First new car to compare.** Required; for example `278198` (Saudi Arabia).\n\nA new-car id (one model year and grade): take `id` from a `/new-cars` row, an id from `years_grades.years_list` of /new-car-details, or a `vehicle_id` from /compare-suggestions, fetched with the same `country`. Older model years work too. Must differ from the other car; an unknown id, a used-listing id or an id from the other market returns 404 naming this parameter.", "name": "vehicle_id_1", "in": "query" }, { "schema": { "type": "integer", "description": "**Second new car to compare.** Required; for example `264600` (Saudi Arabia).\n\nA new-car id (one model year and grade): take `id` from a `/new-cars` row, an id from `years_grades.years_list` of /new-car-details, or a `vehicle_id` from /compare-suggestions, fetched with the same `country`. Older model years work too. Must differ from the other car; an unknown id, a used-listing id or an id from the other market returns 404 naming this parameter.", "minimum": 1, "example": 264600 }, "required": true, "description": "**Second new car to compare.** Required; for example `264600` (Saudi Arabia).\n\nA new-car id (one model year and grade): take `id` from a `/new-cars` row, an id from `years_grades.years_list` of /new-car-details, or a `vehicle_id` from /compare-suggestions, fetched with the same `country`. Older model years work too. Must differ from the other car; an unknown id, a used-listing id or an id from the other market returns 404 naming this parameter.", "name": "vehicle_id_2", "in": "query" }, { "schema": { "type": "string", "description": "**Market to read.** Optional; defaults to `sa`.\n\n- `sa` — Saudi Arabia (prices in SAR)\n- `jo` — Jordan (prices in JOD)\n\nEach market has its own inventory and its own ids (makes, models, cities, body types, dealers, vehicles). Send only ids from a call made with the same `country`. An id from the other market is answered as an unknown id:\n\n- **404** — a lookup by id: every details route, `/models`, `/finance-providers`, and `category_id` on `/category-news` and `/videos`.\n- **400 naming the param** — `make_id`, `model_id` and `finance_provider_id` on `/new-cars` and `/new-car-filters`; `make_id` and `city_id` on `/dealers`; `make_id` and `company_id` on `/offers`; `make_id`, `author_id` and `category_id` as filters of the news lists, and `make_id` on `/videos` (on `/tag-news`, an unknown `author_id` with a tag that is not a make returns an empty list when the tag has articles in the requested `lang`, and 404 otherwise).\n- **Empty result** — every other id filter, for example `body_type_id`, `fuel_type_id`, `transmission_id` or `origin_id` on `/new-cars`, every `/used-cars` and `/used-car-filters` filter, and `dealer_id` on `/dealers`.", "enum": [ "sa", "jo" ], "default": "sa" }, "required": false, "description": "**Market to read.** Optional; defaults to `sa`.\n\n- `sa` — Saudi Arabia (prices in SAR)\n- `jo` — Jordan (prices in JOD)\n\nEach market has its own inventory and its own ids (makes, models, cities, body types, dealers, vehicles). Send only ids from a call made with the same `country`. An id from the other market is answered as an unknown id:\n\n- **404** — a lookup by id: every details route, `/models`, `/finance-providers`, and `category_id` on `/category-news` and `/videos`.\n- **400 naming the param** — `make_id`, `model_id` and `finance_provider_id` on `/new-cars` and `/new-car-filters`; `make_id` and `city_id` on `/dealers`; `make_id` and `company_id` on `/offers`; `make_id`, `author_id` and `category_id` as filters of the news lists, and `make_id` on `/videos` (on `/tag-news`, an unknown `author_id` with a tag that is not a make returns an empty list when the tag has articles in the requested `lang`, and 404 otherwise).\n- **Empty result** — every other id filter, for example `body_type_id`, `fuel_type_id`, `transmission_id` or `origin_id` on `/new-cars`, every `/used-cars` and `/used-car-filters` filter, and `dealer_id` on `/dealers`.", "name": "country", "in": "query" }, { "schema": { "type": "string", "description": "**Response language.** Optional; defaults to `en`.\n\n- `en` — English\n- `ar` — Arabic\n\nChanges labels, titles and descriptions only; ids and numeric values are the same in both languages.", "enum": [ "en", "ar" ], "default": "en" }, "required": false, "description": "**Response language.** Optional; defaults to `en`.\n\n- `en` — English\n- `ar` — Arabic\n\nChanges labels, titles and descriptions only; ids and numeric values are the same in both languages.", "name": "lang", "in": "query" } ], "responses": { "200": { "description": "**Two new cars side by side**, as the marketplace's comparison page shows them.\n\n- `vehicles` — both cars (ids, make/model ids and names, year, grade, price, currency, `price_object`, image, url).\n- `comparison` — a list of categories (technical specifications, safety, luxury, convenience & comfort, entertainment & technology, specifications), each with `compare_data` rows: `section_title` plus `vehicle_1_value` / `vehicle_2_value`, or `vehicle_1_array` / `vehicle_2_array` for feature lists.\n- `similar_comparisons` — other popular pairs that include the first car, with both ids.\n- `title` and `share_link` — the comparison page.\n\nExactly two cars per call; sending the same id twice is rejected with 400; an unknown id returns 404.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MotorySuccessResponseSchema" }, "example": { "success": true, "data": { "title": "Comparison between Changan Alsvin 2027 FULL and Changan Alsvin 2026 FULL", "share_link": "https://ksa.motory.com/en/new-cars/compare/changan-alsvin-full-2027-278198-vs-changan-alsvin-full-2026-264600/", "vehicles": [ { "id": 278198, "title": "Changan Alsvin FULL 2027", "make_id": 83, "make_name": "Changan", "model_id": 517, "model_name": "Alsvin", "year": 2027, "grade": "FULL", "monthly_installment": null, "down_payment": null, "final_payment": null, "total_amount": null, "price": "48,900", "currency": "SR", "image": "https://s3.eu-central-1.amazonaws.com/v3-ncg.motory.com/vehicle-new/l-1652354792.5079-627ceee87bff3.webp", "url": "https://ksa.motory.com/en/new-cars/changan/alsvin/2027/changan-alsvin-full-2027-278198/", "price_object": { "hide_price": false, "price_text": "Cash Price with VAT", "price_value": "48,900", "price_currency": "SR", "price_note": null, "monthly_payment": null, "down_payment": null, "final_payment": null, "total_amount": null, "period": null, "has_financing": true, "finance_text": "Financing", "finance_value": "Available", "disabled_finance_value": false, "disabled_price_value": false, "finance_currency": "", "percentage": null, "show_finance_button": true, "show_cash_button": true, "show_call_button": false } }, { "id": 264600, "title": "Changan Alsvin FULL 2026", "make_id": 83, "make_name": "Changan", "model_id": 517, "model_name": "Alsvin", "year": 2026, "grade": "FULL", "monthly_installment": null, "down_payment": null, "final_payment": null, "total_amount": null, "price": "47,035", "currency": "SR", "image": "https://s3.eu-central-1.amazonaws.com/v3-ncg.motory.com/vehicle-new/l-1652354792.5079-627ceee87bff3.webp", "url": "https://ksa.motory.com/en/new-cars/changan/alsvin/2026/changan-alsvin-full-2026-264600/", "price_object": { "hide_price": false, "price_text": "Price", "price_value": "Unavailable", "price_currency": "", "price_note": null, "monthly_payment": null, "down_payment": null, "final_payment": null, "total_amount": null, "period": null, "has_financing": false, "finance_text": null, "finance_value": null, "disabled_finance_value": true, "disabled_price_value": false, "finance_currency": "", "percentage": null, "show_finance_button": false, "show_cash_button": false, "show_call_button": false } } ], "comparison": [ { "category_id": "technical_specifications", "category_type": "data", "category_title": "Technical Specifications", "compare_data": [ { "section": "fuel_type", "section_type": "data", "section_title": "Fuel Type", "vehicle_1_value": "Gasoline", "vehicle_2_value": "Gasoline", "vehicle_1_array": null, "vehicle_2_array": null } ] }, { "category_id": "safety", "category_type": "mix", "category_title": "Safety", "compare_data": [ { "section": "airbags", "section_type": "data", "section_title": "Airbags", "vehicle_1_value": "2 Airbags", "vehicle_2_value": "2 Airbags", "vehicle_1_array": null, "vehicle_2_array": null }, { "section": "", "section_type": "data_check", "section_title": "Additional", "vehicle_1_value": "", "vehicle_2_value": "", "vehicle_1_array": [ "Tire Pressure Monitoring System" ], "vehicle_2_array": [ "Tire Pressure Monitoring System" ] } ] } ], "similar_comparisons": [ { "url": "https://ksa.motory.com/en/new-cars/compare/changan-alsvin-full-2027-278198-vs-mg-5-std-2026-273809/", "vehicle1_id": 278198, "vehicle2_id": 273809, "vehicle1_title": "Changan Alsvin FULL 2027", "vehicle2_title": "MG 5 STD 2026", "vehicle1_image": "https://s3.eu-central-1.amazonaws.com/v3-ncg.motory.com/vehicle-new/l-1652354792.5079-627ceee87bff3.webp", "vehicle2_image": "https://s3.eu-central-1.amazonaws.com/v3-ncg.motory.com/vehicle-new/l-1742203862.3169-67d7ebd64d5ea.webp" } ] } } } } }, "400": { "description": "Bad request — a parameter is missing, malformed or out of range", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MotoryErrorResponseSchema" } } } }, "404": { "description": "Not found — the requested id or link does not exist", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MotoryErrorResponseSchema" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MotoryErrorResponseSchema" } } } }, "503": { "description": "Service busy — retry shortly", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MotoryErrorResponseSchema" } } } } } } }, "/compare-suggestions": { "get": { "tags": [ "New Cars" ], "operationId": "getCompareSuggestions", "description": "Find new cars to compare: the cars most often compared with a given new car, or the market's most-compared cars this week. Optional vehicle_id from /new-cars; pass two ids on to /compare-new-cars.", "parameters": [ { "schema": { "type": "integer", "description": "**New car to find comparison partners for.** Optional; a new-car id.\n\n- set — the cars most often compared with this car\n- omitted — the market's most-compared cars this week\n\nTake `id` from a `/new-cars` row or /new-car-details, fetched with the same `country`. An unknown id, a used-listing id or an id from the other market returns 404.", "minimum": 1 }, "required": false, "description": "**New car to find comparison partners for.** Optional; a new-car id.\n\n- set — the cars most often compared with this car\n- omitted — the market's most-compared cars this week\n\nTake `id` from a `/new-cars` row or /new-car-details, fetched with the same `country`. An unknown id, a used-listing id or an id from the other market returns 404.", "name": "vehicle_id", "in": "query" }, { "schema": { "type": "string", "description": "**Market to read.** Optional; defaults to `sa`.\n\n- `sa` — Saudi Arabia (prices in SAR)\n- `jo` — Jordan (prices in JOD)\n\nEach market has its own inventory and its own ids (makes, models, cities, body types, dealers, vehicles). Send only ids from a call made with the same `country`. An id from the other market is answered as an unknown id:\n\n- **404** — a lookup by id: every details route, `/models`, `/finance-providers`, and `category_id` on `/category-news` and `/videos`.\n- **400 naming the param** — `make_id`, `model_id` and `finance_provider_id` on `/new-cars` and `/new-car-filters`; `make_id` and `city_id` on `/dealers`; `make_id` and `company_id` on `/offers`; `make_id`, `author_id` and `category_id` as filters of the news lists, and `make_id` on `/videos` (on `/tag-news`, an unknown `author_id` with a tag that is not a make returns an empty list when the tag has articles in the requested `lang`, and 404 otherwise).\n- **Empty result** — every other id filter, for example `body_type_id`, `fuel_type_id`, `transmission_id` or `origin_id` on `/new-cars`, every `/used-cars` and `/used-car-filters` filter, and `dealer_id` on `/dealers`.", "enum": [ "sa", "jo" ], "default": "sa" }, "required": false, "description": "**Market to read.** Optional; defaults to `sa`.\n\n- `sa` — Saudi Arabia (prices in SAR)\n- `jo` — Jordan (prices in JOD)\n\nEach market has its own inventory and its own ids (makes, models, cities, body types, dealers, vehicles). Send only ids from a call made with the same `country`. An id from the other market is answered as an unknown id:\n\n- **404** — a lookup by id: every details route, `/models`, `/finance-providers`, and `category_id` on `/category-news` and `/videos`.\n- **400 naming the param** — `make_id`, `model_id` and `finance_provider_id` on `/new-cars` and `/new-car-filters`; `make_id` and `city_id` on `/dealers`; `make_id` and `company_id` on `/offers`; `make_id`, `author_id` and `category_id` as filters of the news lists, and `make_id` on `/videos` (on `/tag-news`, an unknown `author_id` with a tag that is not a make returns an empty list when the tag has articles in the requested `lang`, and 404 otherwise).\n- **Empty result** — every other id filter, for example `body_type_id`, `fuel_type_id`, `transmission_id` or `origin_id` on `/new-cars`, every `/used-cars` and `/used-car-filters` filter, and `dealer_id` on `/dealers`.", "name": "country", "in": "query" }, { "schema": { "type": "string", "description": "**Response language.** Optional; defaults to `en`.\n\n- `en` — English\n- `ar` — Arabic\n\nChanges labels, titles and descriptions only; ids and numeric values are the same in both languages.", "enum": [ "en", "ar" ], "default": "en" }, "required": false, "description": "**Response language.** Optional; defaults to `en`.\n\n- `en` — English\n- `ar` — Arabic\n\nChanges labels, titles and descriptions only; ids and numeric values are the same in both languages.", "name": "lang", "in": "query" } ], "responses": { "200": { "description": "**Cars to compare**: the new cars most often compared with a given car, or, without `vehicle_id`, the market's most-compared cars this week.\n\n- `title` — the list heading as served (\"Often Compared with\" / \"Most Compared this Week\", localised).\n- `items` — rows with `vehicle_id`, `title`, `image` and the button label as served; pass two ids to `/compare-new-cars`.\n- A real new car that nobody compares (often an older model year) returns an empty `items` list; `title` is still the heading as served (there the weekly one).\n- An id that is not a new car of the selected market returns 404.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MotorySuccessResponseSchema" }, "example": { "success": true, "data": { "title": "Most Compared this Week", "items": [ { "vehicle_id": 264258, "image": "https://s3.eu-central-1.amazonaws.com/v3-ncg.motory.com/vehicle-new/466x350/l-1747905249.1049-682eeae1199ab_outbound.webp", "title": "Jetour T1 Luxury 2025", "button": "Add to comparison" } ] } } } } }, "400": { "description": "Bad request — a parameter is missing, malformed or out of range", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MotoryErrorResponseSchema" } } } }, "404": { "description": "Not found — the requested id or link does not exist", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MotoryErrorResponseSchema" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MotoryErrorResponseSchema" } } } }, "503": { "description": "Service busy — retry shortly", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MotoryErrorResponseSchema" } } } } } } }, "/search": { "get": { "tags": [ "Search" ], "operationId": "searchMotory", "description": "Search all of Motory by keyword across used and new cars, offers, the Saudi business directory, news and videos. Takes a keyword, an optional tab and an optional category within it; open a row with the detail endpoint its index_name points to.", "parameters": [ { "schema": { "type": "string", "description": "**What to search for.** Required; for example `toyota`, `toyota camry`, `spare parts`, or Arabic `تويوتا`.\n\nWhat the search matches:\n\n- Make names and \"make model\" phrases in every section, and some other known phrases (for example `electric cars` on `news`).\n- In the business directory (`tab=directory`), business names, services (`spare parts`) and make names. A single other known word (for example `golden`), or a service inside a directory `category`, re-orders the whole directory or category by relevance instead of narrowing it; `pagination.total_pages` then stays that of the whole directory or category.\n- Other words in a keyword can be ignored without notice: the results are then those of the words that match. For example, on `tab=used_cars` `toyota xyz` and `toyota 2024` return the results for `toyota`, and `mercedes benz` the results for `mercedes`.\n\nRejected with 400:\n\n- A keyword the search does not recognise at all on the tab (for example `xyzqq`), also within a directory `category`.\n- A keyword of digits only (for example `2025`): for model years use `min_year`/`max_year` on `/used-cars` or `/new-cars`.\n\nTo filter cars exactly by make and model, take `make_id`/`model_id` from `/search-suggestions` and pass them to `/used-cars` or `/new-cars`.", "example": "toyota", "maxLength": 100 }, "required": true, "description": "**What to search for.** Required; for example `toyota`, `toyota camry`, `spare parts`, or Arabic `تويوتا`.\n\nWhat the search matches:\n\n- Make names and \"make model\" phrases in every section, and some other known phrases (for example `electric cars` on `news`).\n- In the business directory (`tab=directory`), business names, services (`spare parts`) and make names. A single other known word (for example `golden`), or a service inside a directory `category`, re-orders the whole directory or category by relevance instead of narrowing it; `pagination.total_pages` then stays that of the whole directory or category.\n- Other words in a keyword can be ignored without notice: the results are then those of the words that match. For example, on `tab=used_cars` `toyota xyz` and `toyota 2024` return the results for `toyota`, and `mercedes benz` the results for `mercedes`.\n\nRejected with 400:\n\n- A keyword the search does not recognise at all on the tab (for example `xyzqq`), also within a directory `category`.\n- A keyword of digits only (for example `2025`): for model years use `min_year`/`max_year` on `/used-cars` or `/new-cars`.\n\nTo filter cars exactly by make and model, take `make_id`/`model_id` from `/search-suggestions` and pass them to `/used-cars` or `/new-cars`.", "name": "keyword", "in": "query" }, { "schema": { "type": "string", "description": "**Section to search.** Optional; defaults to `all`.\n\n- `all` — the top matches of every section together (a short mixed list)\n- `used_cars` — used cars for sale\n- `new_cars` — new cars, including older model years no longer sold\n- `offers` — dealer and finance offers\n- `directory` — automotive businesses: workshops, spare parts, car wash, rentals… (`country=sa` only)\n- `news` — news articles\n- `videos` — videos", "enum": [ "all", "used_cars", "new_cars", "offers", "directory", "news", "videos" ], "default": "all" }, "required": false, "description": "**Section to search.** Optional; defaults to `all`.\n\n- `all` — the top matches of every section together (a short mixed list)\n- `used_cars` — used cars for sale\n- `new_cars` — new cars, including older model years no longer sold\n- `offers` — dealer and finance offers\n- `directory` — automotive businesses: workshops, spare parts, car wash, rentals… (`country=sa` only)\n- `news` — news articles\n- `videos` — videos", "name": "tab", "in": "query" }, { "schema": { "type": "string", "description": "**One category within the section.** Optional; for `tab=directory` (for example `Car Spare Parts`, `Car Wash`, `Tire Shop`) or `tab=news` (for example `Car News`, `Local News`).\n\nAccepted values are the `value` fields of the `categories` list the same search returns; matching ignores case. Any other value, or a category on another tab, is rejected with 400.", "maxLength": 80 }, "required": false, "description": "**One category within the section.** Optional; for `tab=directory` (for example `Car Spare Parts`, `Car Wash`, `Tire Shop`) or `tab=news` (for example `Car News`, `Local News`).\n\nAccepted values are the `value` fields of the `categories` list the same search returns; matching ignores case. Any other value, or a category on another tab, is rejected with 400.", "name": "category", "in": "query" }, { "schema": { "type": "integer", "description": "**Page number, starting at 1.** Optional; defaults to `1`, at most `1000`.\n\nPages hold 10 rows; stop at `pagination.total_pages`. The search serves results up to page 1000; a `page` beyond the last page (up to 1000) returns an empty `items` list.", "minimum": 1, "maximum": 1000, "default": 1 }, "required": false, "description": "**Page number, starting at 1.** Optional; defaults to `1`, at most `1000`.\n\nPages hold 10 rows; stop at `pagination.total_pages`. The search serves results up to page 1000; a `page` beyond the last page (up to 1000) returns an empty `items` list.", "name": "page", "in": "query" }, { "schema": { "type": "string", "description": "**Market to read.** Optional; defaults to `sa`.\n\n- `sa` — Saudi Arabia (prices in SAR)\n- `jo` — Jordan (prices in JOD)\n\nEach market has its own inventory and its own ids (makes, models, cities, body types, dealers, vehicles). Send only ids from a call made with the same `country`. An id from the other market is answered as an unknown id:\n\n- **404** — a lookup by id: every details route, `/models`, `/finance-providers`, and `category_id` on `/category-news` and `/videos`.\n- **400 naming the param** — `make_id`, `model_id` and `finance_provider_id` on `/new-cars` and `/new-car-filters`; `make_id` and `city_id` on `/dealers`; `make_id` and `company_id` on `/offers`; `make_id`, `author_id` and `category_id` as filters of the news lists, and `make_id` on `/videos` (on `/tag-news`, an unknown `author_id` with a tag that is not a make returns an empty list when the tag has articles in the requested `lang`, and 404 otherwise).\n- **Empty result** — every other id filter, for example `body_type_id`, `fuel_type_id`, `transmission_id` or `origin_id` on `/new-cars`, every `/used-cars` and `/used-car-filters` filter, and `dealer_id` on `/dealers`.", "enum": [ "sa", "jo" ], "default": "sa" }, "required": false, "description": "**Market to read.** Optional; defaults to `sa`.\n\n- `sa` — Saudi Arabia (prices in SAR)\n- `jo` — Jordan (prices in JOD)\n\nEach market has its own inventory and its own ids (makes, models, cities, body types, dealers, vehicles). Send only ids from a call made with the same `country`. An id from the other market is answered as an unknown id:\n\n- **404** — a lookup by id: every details route, `/models`, `/finance-providers`, and `category_id` on `/category-news` and `/videos`.\n- **400 naming the param** — `make_id`, `model_id` and `finance_provider_id` on `/new-cars` and `/new-car-filters`; `make_id` and `city_id` on `/dealers`; `make_id` and `company_id` on `/offers`; `make_id`, `author_id` and `category_id` as filters of the news lists, and `make_id` on `/videos` (on `/tag-news`, an unknown `author_id` with a tag that is not a make returns an empty list when the tag has articles in the requested `lang`, and 404 otherwise).\n- **Empty result** — every other id filter, for example `body_type_id`, `fuel_type_id`, `transmission_id` or `origin_id` on `/new-cars`, every `/used-cars` and `/used-car-filters` filter, and `dealer_id` on `/dealers`.", "name": "country", "in": "query" }, { "schema": { "type": "string", "description": "**Response language.** Optional; defaults to `en`.\n\n- `en` — English\n- `ar` — Arabic\n\nChanges labels, titles and descriptions only; ids and numeric values are the same in both languages.", "enum": [ "en", "ar" ], "default": "en" }, "required": false, "description": "**Response language.** Optional; defaults to `en`.\n\n- `en` — English\n- `ar` — Arabic\n\nChanges labels, titles and descriptions only; ids and numeric values are the same in both languages.", "name": "lang", "in": "query" } ], "responses": { "200": { "description": "**Search all of Motory by keyword** — used and new cars (including older model years no longer sold), offers, the Saudi business directory (businesses by name or service), news and videos — one section at a time or all together.\n\nEach row is `{id, index_name, title, description, slug, image, category, category_url, sub_category, sub_category_url, address, published_at}`. `slug` is its public page link; `category_url` / `sub_category_url` link its section pages (null when the section has none). `index_name` says what the row is and which route takes it:\n\n- `vehicle` — a used or new car (`category` tells which): `id` with `/used-car-details` or `/new-car-details`\n- `car_offer` — an offer: `id` with `/offer-details`\n- `directory` — a business or a company: pass its `slug` to `/resolve-url`, which returns its `business_id` or `company_id`; `category` is the directory itself (\"Motory Guide\") and `sub_category` is the business's city\n- `news` — a news article: `id` with `/news-details`\n- `video` — a video: `id` with `/video-details`\n\nPages hold 10 rows. `pagination.total_pages` counts pages; no item total is published (`total_items` is null).\n\n`categories` is the section's category list on `tab=directory` and `tab=news` (its `value` fields are what `category` accepts) and `null` on the other tabs.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MotorySuccessResponseSchema" }, "example": { "success": true, "data": { "items": [ { "id": 4802, "index_name": "car_offer", "title": "Watani Auto offers you an easier way to own a Toyota.", "description": "A new offer has been launched by Watani Auto for Toyota 2024, Toyota 2026 cars in Saudi Arabia on 06/10/2026 and will end on 31/10/2026. The cars included in the offer are Toyota Corolla Cross 2024 LE, Toyota Corolla 2024 Xli1.5L, Toyota Yaris 2026 Y PLUS, Toyota Camry 2024 LE STANDARD. You can view the phone number of Watani Auto or call the company directly if you're using your mobile device to inquire about this offer.\r\nFinancing is provided by Watani Auto, and you can choose the car most suitable for you, fill out the finance application form, then submit your application and Motory will deliver it directly to Watani Auto and Watani Auto, who will contact you the soonest possible to process your request and take you forward.", "slug": "https://ksa.motory.com/en/cars-offers/watani-auto-offers-you-an-easier-way-to-own-a-toyota-4802/", "address": null, "category": "Car Offers", "category_url": "https://ksa.motory.com/en/cars-offers/", "sub_category": null, "sub_category_url": null, "image": "https://s3.eu-central-1.amazonaws.com/v3-car-offer.motory.com/car-offer/468x351/l-1791274874.6678-6ac4af7aa308e.webp", "published_at": "2026-10-06 11:31:41" } ], "categories": null, "pagination": { "page": 1, "page_size": 10, "total_items": null, "total_pages": 5 } } } } } }, "400": { "description": "Bad request — a parameter is missing, malformed or out of range", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MotoryErrorResponseSchema" } } } }, "404": { "description": "Not found — the requested id or link does not exist", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MotoryErrorResponseSchema" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MotoryErrorResponseSchema" } } } }, "503": { "description": "Service busy — retry shortly", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MotoryErrorResponseSchema" } } } } } } }, "/search-suggestions": { "get": { "tags": [ "Search" ], "operationId": "getSearchSuggestions", "description": "Turn typed text into make, model and year suggestions that carry ids, for used or new cars. Takes a keyword and a condition; pass the returned make_id and model_id to /used-cars or /new-cars.", "parameters": [ { "schema": { "type": "string", "description": "**What the user has typed so far**, in English or Arabic. Required; for example `hilux`, `toy` or `تو`.\n\nMake and model names (and their beginnings) are matched. Text with no matching make or model returns an empty `items` list. Text that gets no suggestion at all on either condition (some very short or common inputs and some model names) returns 404 — list ids with `/makes` and `/models` instead.", "example": "hilux", "maxLength": 100 }, "required": true, "description": "**What the user has typed so far**, in English or Arabic. Required; for example `hilux`, `toy` or `تو`.\n\nMake and model names (and their beginnings) are matched. Text with no matching make or model returns an empty `items` list. Text that gets no suggestion at all on either condition (some very short or common inputs and some model names) returns 404 — list ids with `/makes` and `/models` instead.", "name": "keyword", "in": "query" }, { "schema": { "type": "string", "description": "**Which listings the suggestions lead to.** Required.\n\n- `used` — used cars for sale (suggestions for `/used-cars`)\n- `new` — new cars (suggestions for `/new-cars`, plus the make's offers page)", "enum": [ "used", "new" ], "example": "used" }, "required": true, "description": "**Which listings the suggestions lead to.** Required.\n\n- `used` — used cars for sale (suggestions for `/used-cars`)\n- `new` — new cars (suggestions for `/new-cars`, plus the make's offers page)", "name": "condition", "in": "query" }, { "schema": { "type": "string", "description": "**Market to read.** Optional; defaults to `sa`.\n\n- `sa` — Saudi Arabia (prices in SAR)\n- `jo` — Jordan (prices in JOD)\n\nEach market has its own inventory and its own ids (makes, models, cities, body types, dealers, vehicles). Send only ids from a call made with the same `country`. An id from the other market is answered as an unknown id:\n\n- **404** — a lookup by id: every details route, `/models`, `/finance-providers`, and `category_id` on `/category-news` and `/videos`.\n- **400 naming the param** — `make_id`, `model_id` and `finance_provider_id` on `/new-cars` and `/new-car-filters`; `make_id` and `city_id` on `/dealers`; `make_id` and `company_id` on `/offers`; `make_id`, `author_id` and `category_id` as filters of the news lists, and `make_id` on `/videos` (on `/tag-news`, an unknown `author_id` with a tag that is not a make returns an empty list when the tag has articles in the requested `lang`, and 404 otherwise).\n- **Empty result** — every other id filter, for example `body_type_id`, `fuel_type_id`, `transmission_id` or `origin_id` on `/new-cars`, every `/used-cars` and `/used-car-filters` filter, and `dealer_id` on `/dealers`.", "enum": [ "sa", "jo" ], "default": "sa" }, "required": false, "description": "**Market to read.** Optional; defaults to `sa`.\n\n- `sa` — Saudi Arabia (prices in SAR)\n- `jo` — Jordan (prices in JOD)\n\nEach market has its own inventory and its own ids (makes, models, cities, body types, dealers, vehicles). Send only ids from a call made with the same `country`. An id from the other market is answered as an unknown id:\n\n- **404** — a lookup by id: every details route, `/models`, `/finance-providers`, and `category_id` on `/category-news` and `/videos`.\n- **400 naming the param** — `make_id`, `model_id` and `finance_provider_id` on `/new-cars` and `/new-car-filters`; `make_id` and `city_id` on `/dealers`; `make_id` and `company_id` on `/offers`; `make_id`, `author_id` and `category_id` as filters of the news lists, and `make_id` on `/videos` (on `/tag-news`, an unknown `author_id` with a tag that is not a make returns an empty list when the tag has articles in the requested `lang`, and 404 otherwise).\n- **Empty result** — every other id filter, for example `body_type_id`, `fuel_type_id`, `transmission_id` or `origin_id` on `/new-cars`, every `/used-cars` and `/used-car-filters` filter, and `dealer_id` on `/dealers`.", "name": "country", "in": "query" }, { "schema": { "type": "string", "description": "**Response language.** Optional; defaults to `en`.\n\n- `en` — English\n- `ar` — Arabic\n\nChanges labels, titles and descriptions only; ids and numeric values are the same in both languages.", "enum": [ "en", "ar" ], "default": "en" }, "required": false, "description": "**Response language.** Optional; defaults to `en`.\n\n- `en` — English\n- `ar` — Arabic\n\nChanges labels, titles and descriptions only; ids and numeric values are the same in both languages.", "name": "lang", "in": "query" } ], "responses": { "200": { "description": "**Turn typed text into car-search suggestions that carry ids** — \"hilux\" → Toyota Hilux with `make_id`, `model_id` and per-year rows — ready for `/used-cars` or `/new-cars`.\n\nEach row is `{section, make_id, make_name, model_id, model_name, year, label, url}`; `model_id` and `year` are null on make-level rows. `url` is the page link exactly as published. `section` says which listing the row leads to:\n\n- `vehicle-used` — used cars; its `url` is the new-car page of that make or model, not a used-car search page\n- `vehicle-new` — new cars\n- `cars-offers` — the make's offers page\n\nSome texts get no answer for one `condition`; the suggestions of the other condition are then returned (their `section` shows it). Make and model ids are the same for used and new cars within a market, so their `make_id` / `model_id` work with both `/used-cars` and `/new-cars`.\n\nNo match returns an empty `items` list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MotorySuccessResponseSchema" }, "example": { "success": true, "data": { "items": [ { "section": "vehicle-used", "make_id": 90, "make_name": "Toyota", "model_id": 408, "model_name": "Hilux", "year": null, "label": "Toyota Hilux in Cars For Sale", "url": "https://ksa.motory.com/en/new-cars/toyota/hilux/" } ] } } } } }, "400": { "description": "Bad request — a parameter is missing, malformed or out of range", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MotoryErrorResponseSchema" } } } }, "404": { "description": "Not found — the requested id or link does not exist", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MotoryErrorResponseSchema" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MotoryErrorResponseSchema" } } } }, "503": { "description": "Service busy — retry shortly", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MotoryErrorResponseSchema" } } } } } } }, "/resolve-url": { "get": { "tags": [ "Search" ], "operationId": "resolveUrl", "description": "Identify any ksa.motory.com or jo.motory.com page link and return its page type with the ids it carries (vehicle, make, model, year, city, dealer, offer, news, video, news or video category, author, directory service, business or company), including make pages, site search pages and information pages. Takes a url; use the ids with the matching detail or list endpoint.", "parameters": [ { "schema": { "type": "string", "description": "**Any page link** on ksa.motory.com (Saudi Arabia) or jo.motory.com (Jordan), English or Arabic. Required.\n\n- Read: used and new car pages, make/model/city/year search pages (with filter parameters), dealer, offer, news, video and business-directory pages, site search pages and the site's information pages.\n- A link to another site → 400.\n- A link that does not lead to a live page (unknown id or slug, mistyped path) → 404.\n- A link without `/en/` or `/ar/` after the host is read in the language its path is written in; the bare host is the Arabic home page.", "example": "https://ksa.motory.com/en/cars-for-sale/riyadh-haraj/toyota/camry/2024/", "maxLength": 2000 }, "required": true, "description": "**Any page link** on ksa.motory.com (Saudi Arabia) or jo.motory.com (Jordan), English or Arabic. Required.\n\n- Read: used and new car pages, make/model/city/year search pages (with filter parameters), dealer, offer, news, video and business-directory pages, site search pages and the site's information pages.\n- A link to another site → 400.\n- A link that does not lead to a live page (unknown id or slug, mistyped path) → 404.\n- A link without `/en/` or `/ar/` after the host is read in the language its path is written in; the bare host is the Arabic home page.", "name": "url", "in": "query" } ], "responses": { "200": { "description": "**Identify any motory.com page link and get its ids.** The answer gives the page type plus whichever ids the page has: `vehicle_id`, `make_id`, `model_id`, `year`, `city_id`, `dealer_id`, `offer_id`, `news_id`, `video_id`, `category_id` (a news or video category), `author_id`, `service_id`, `business_id` or `company_id`. Fields a page does not have are null or absent.\n\n`url_type` names the page family:\n\n- `vehicle-used`, `vehicle-new` — used and new car pages. A make's page (`/en/toyota/`) comes back as `vehicle-new` with its `make_id` and no `type`.\n- `dealer` — dealer pages. A dealer link in the form a dealer profile shares (`/en/cars-dealers//-/`) is answered for the page it leads to, with its `dealer_id`.\n- `car-offer` — offer pages.\n- `news` — news pages; `reels` — a news reels link (`/ar/الاخبار/?hash=…`).\n- `video` — video pages.\n- `compare` — a new-car comparison link, with `type: index` and no ids (compare cars with `/compare-new-cars`).\n- `directory-detail`, `directory-listing`, `directory-home` — business-directory pages.\n- `search` — a site search page (`/en/search/?keyword=…`); search with `/search`.\n- `electric-cars`, `valuation`, `loan-calculator`, `all-makes`, `vehicles-new-quick-filters`, `home` — the site's other sections.\n- The page's own name (for example `about-motory`, `faqs`, `car-finance`) — the site's information pages (about, contact, FAQs, terms, privacy, car finance, buying guides), with a `page_id` and no other ids. Their content is not served by this API.\n\n`type` names the kind of page within its family:\n\n- `detail`, `index-listing`, `index`, `offers_by_make`, `offers_by_company`, `news_by_category`, `author`.\n- `business` or `company` — directory pages.\n- No `type` — `home`, `all-makes`, `loan-calculator`, `directory-home`, `directory-listing`, `search`, and a make's page.\n\nA search page's filter parameters come back in `parameters` as written in the link. `has_financing: true` there (plus `pricing_value`) marks a financing page such as `/en/cars-for-sale/used-cars-financing/`; `has_financing: false` is present on every other link and does not describe it. `lang` is the language of the link, and the market is taken from the link's host.\n\nNext calls:\n\n- The returned id → `/used-car-details`, `/new-car-details`, `/dealer-details`, `/offer-details`, `/news-details`, `/video-details`, `/directory-business-details` or `/directory-company-details`.\n- A news category page's `category_id` → `/category-news`; an author page's `author_id` → `/author-news`; a video category page's `category_id` → `/videos`.\n- Car pages: `/used-car-details-by-url`, `/new-car-details-by-url`, `/used-cars-by-url` and `/new-cars-by-url` take the link directly (a make's page: either search route, as that make).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MotorySuccessResponseSchema" }, "example": { "success": true, "data": { "url_type": "vehicle-used", "show_switch_country": false, "switch_to_country": null, "lang": "en", "vehicle_id": null, "make_id": 90, "make_name": "Toyota", "make_logo": "https://s3.eu-central-1.amazonaws.com/v3-common.motory.com/taxonomy/l-1669878465.8496-638852c1cf6f3.webp", "model_id": 429, "model_name": "Camry", "year": "2024", "city_id": 810, "city_name": "Riyadh", "page_id": null, "company_id": null, "company_name": null, "company_logo": null, "offer_id": null, "dealer_id": null, "news_id": null, "lead_id": null, "response_id": null, "parameters": { "has_financing": false }, "category_id": null, "video_id": null, "notification_id": null, "external_link": null, "message": null, "redirect_url": null, "redirect_status_code": null, "open_form": false, "type": "index-listing" } } } } }, "400": { "description": "Bad request — a parameter is missing, malformed or out of range", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MotoryErrorResponseSchema" } } } }, "404": { "description": "Not found — the requested id or link does not exist", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MotoryErrorResponseSchema" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MotoryErrorResponseSchema" } } } }, "503": { "description": "Service busy — retry shortly", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MotoryErrorResponseSchema" } } } } } } }, "/dealers": { "get": { "tags": [ "Dealers" ], "operationId": "listDealers", "description": "List the marketplace's showcased car dealers and showrooms (in Saudi Arabia the featured dealers), optionally for one make, one city or one dealer, with stock counts and a preview of their cars. Take ids from this endpoint's filter_lists or /makes; open a dealer_id in /dealer-details.", "parameters": [ { "schema": { "type": "string", "description": "**Market to read.** Optional; defaults to `sa`.\n\n- `sa` — Saudi Arabia (prices in SAR)\n- `jo` — Jordan (prices in JOD)\n\nEach market has its own inventory and its own ids (makes, models, cities, body types, dealers, vehicles). Send only ids from a call made with the same `country`. An id from the other market is answered as an unknown id:\n\n- **404** — a lookup by id: every details route, `/models`, `/finance-providers`, and `category_id` on `/category-news` and `/videos`.\n- **400 naming the param** — `make_id`, `model_id` and `finance_provider_id` on `/new-cars` and `/new-car-filters`; `make_id` and `city_id` on `/dealers`; `make_id` and `company_id` on `/offers`; `make_id`, `author_id` and `category_id` as filters of the news lists, and `make_id` on `/videos` (on `/tag-news`, an unknown `author_id` with a tag that is not a make returns an empty list when the tag has articles in the requested `lang`, and 404 otherwise).\n- **Empty result** — every other id filter, for example `body_type_id`, `fuel_type_id`, `transmission_id` or `origin_id` on `/new-cars`, every `/used-cars` and `/used-car-filters` filter, and `dealer_id` on `/dealers`.", "enum": [ "sa", "jo" ], "default": "sa" }, "required": false, "description": "**Market to read.** Optional; defaults to `sa`.\n\n- `sa` — Saudi Arabia (prices in SAR)\n- `jo` — Jordan (prices in JOD)\n\nEach market has its own inventory and its own ids (makes, models, cities, body types, dealers, vehicles). Send only ids from a call made with the same `country`. An id from the other market is answered as an unknown id:\n\n- **404** — a lookup by id: every details route, `/models`, `/finance-providers`, and `category_id` on `/category-news` and `/videos`.\n- **400 naming the param** — `make_id`, `model_id` and `finance_provider_id` on `/new-cars` and `/new-car-filters`; `make_id` and `city_id` on `/dealers`; `make_id` and `company_id` on `/offers`; `make_id`, `author_id` and `category_id` as filters of the news lists, and `make_id` on `/videos` (on `/tag-news`, an unknown `author_id` with a tag that is not a make returns an empty list when the tag has articles in the requested `lang`, and 404 otherwise).\n- **Empty result** — every other id filter, for example `body_type_id`, `fuel_type_id`, `transmission_id` or `origin_id` on `/new-cars`, every `/used-cars` and `/used-car-filters` filter, and `dealer_id` on `/dealers`.", "name": "country", "in": "query" }, { "schema": { "type": "string", "description": "**Response language.** Optional; defaults to `en`.\n\n- `en` — English\n- `ar` — Arabic\n\nChanges labels, titles and descriptions only; ids and numeric values are the same in both languages.", "enum": [ "en", "ar" ], "default": "en" }, "required": false, "description": "**Response language.** Optional; defaults to `en`.\n\n- `en` — English\n- `ar` — Arabic\n\nChanges labels, titles and descriptions only; ids and numeric values are the same in both languages.", "name": "lang", "in": "query" }, { "schema": { "type": "integer", "description": "**Only dealers selling this make.** Optional; one make id (for example `90`).\n\nTake ids from `filter_lists.makes_list` of this endpoint (makes that have dealers) or from `/makes`, called with the same `country`. One value only — a comma-separated list is rejected with 400. A make of this market that no listed dealer sells returns an empty list; an id that is not a make of this market is rejected with 400.", "minimum": 1 }, "required": false, "description": "**Only dealers selling this make.** Optional; one make id (for example `90`).\n\nTake ids from `filter_lists.makes_list` of this endpoint (makes that have dealers) or from `/makes`, called with the same `country`. One value only — a comma-separated list is rejected with 400. A make of this market that no listed dealer sells returns an empty list; an id that is not a make of this market is rejected with 400.", "name": "make_id", "in": "query" }, { "schema": { "type": "integer", "description": "**Only dealers serving this city.** Optional; one city id.\n\nTake ids from `filter_lists.cities` of this endpoint or from `/used-car-filters` (cities), called with the same `country`. Dealers whose `city` is the all-cities label (\"All Cities\"; \"كل المدن\" with `lang=ar`) serve every city and are always kept; the filter removes dealers tied to another city. One value only; an id that is not in `filter_lists.cities` (for example a city of the other market) is rejected with 400.", "minimum": 1 }, "required": false, "description": "**Only dealers serving this city.** Optional; one city id.\n\nTake ids from `filter_lists.cities` of this endpoint or from `/used-car-filters` (cities), called with the same `country`. Dealers whose `city` is the all-cities label (\"All Cities\"; \"كل المدن\" with `lang=ar`) serve every city and are always kept; the filter removes dealers tied to another city. One value only; an id that is not in `filter_lists.cities` (for example a city of the other market) is rejected with 400.", "name": "city_id", "in": "query" }, { "schema": { "type": "integer", "description": "**One dealer only.** Optional; one dealer id (for example `454541`).\n\nTake ids from `filter_lists.dealers_name` of this endpoint (`dealer_id`), called with the same `country`. A dealer that is not in this list (see the endpoint description) returns an empty list — read any dealer with `/dealer-details`.", "minimum": 1 }, "required": false, "description": "**One dealer only.** Optional; one dealer id (for example `454541`).\n\nTake ids from `filter_lists.dealers_name` of this endpoint (`dealer_id`), called with the same `country`. A dealer that is not in this list (see the endpoint description) returns an empty list — read any dealer with `/dealer-details`.", "name": "dealer_id", "in": "query" }, { "schema": { "type": "integer", "description": "**Page number, starting at 1.** Optional; defaults to `1`.\n\nKeep `page_size` fixed while paging and stop at `pagination.total_pages`. A `page` beyond the last page returns an empty `items` list.", "minimum": 1, "maximum": 10000, "default": 1 }, "required": false, "description": "**Page number, starting at 1.** Optional; defaults to `1`.\n\nKeep `page_size` fixed while paging and stop at `pagination.total_pages`. A `page` beyond the last page returns an empty `items` list.", "name": "page", "in": "query" }, { "schema": { "type": "integer", "description": "**Results per page.** Optional; defaults to `20`, accepts 1–50.\n\nValues above 50 are rejected with 400. Keep the same `page_size` on every page of one search so pages neither overlap nor skip results.", "minimum": 1, "maximum": 50, "default": 20 }, "required": false, "description": "**Results per page.** Optional; defaults to `20`, accepts 1–50.\n\nValues above 50 are rejected with 400. Keep the same `page_size` on every page of one search so pages neither overlap nor skip results.", "name": "page_size", "in": "query" } ], "responses": { "200": { "description": "**The marketplace's showcased car dealers and showrooms**, optionally narrowed to one make, one city or one dealer.\n\nIn Saudi Arabia the list holds featured dealers only (`is_featured: true`). A dealer that is not in the list can still be read by id with `/dealer-details` (for example a `seller_id` from a `/used-cars` row).\n\nEach row is a dealer card as served:\n\n- `dealer_id`, `dealer_name`, `image` and `is_featured`.\n- `package_tag` — the dealer's listing package as the market names it (for example VIP or Platinum); null when the dealer has none.\n- `city` — for dealers serving the whole country, the all-cities label (\"All Cities\"; \"كل المدن\" with `lang=ar`).\n- `vehicles_count` — number of cars listed, as a string.\n- `vehicle_type` — the kind of cars the dealer sells, as the market labels it in the response language (for example New, Used, New & Used or Certified Pre-Owned).\n- `vehicles_list` — a preview of up to 7 of the dealer's cars, not the whole stock.\n\nRelated data:\n\n- `filter_lists` — the vocabularies of this endpoint's filters: `cities` (`city_id`), `dealers_name` (`dealer_id`) and `makes_list` (`make_id`, makes that have listed dealers).\n- `filter_lists.cities` starts with `{id: -1, name: \"All\"}`, the \"All\" entry of the site's city picker. To get all cities, omit `city_id`: `-1` is not a filter value and is rejected with 400.\n- Read a dealer's profile with `/dealer-details` and its full stock with `/used-cars?dealer_id=` (every car a dealer lists, zero-mileage ones included, is in the used-car search).\n- `pagination.total_items` counts every matching dealer; a `page` past `pagination.total_pages` returns an empty `items` list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MotorySuccessResponseSchema" }, "example": { "success": true, "data": { "items": [ { "dealer_id": 454541, "dealer_name": "Shop By Motory", "package_tag": "VIP", "image": "https://s3.eu-central-1.amazonaws.com/v3-companies.motory.com/dealer/l-1698915852.7377-6543660cb41b6.webp", "url": null, "city": "All Cities", "is_featured": true, "vehicles_count": "215", "vehicle_type": "New & Used", "vehicles_list": [ { "vehicle_id": 281811, "title": "Toyota Corolla XLI 2024", "image": "https://s3.eu-central-1.amazonaws.com/v3-cfs.motory.com/vehicle-used/l-1791810718.0863-6accdc9e150f8.webp", "price_text": "Cash Price", "price": "57,500", "currency": "SR" } ] } ], "filter_lists": { "cities": [ { "id": -1, "name": "All" } ], "dealers_name": [ { "dealer_id": 283165, "dealer_name": "Abdul Latif Jameel United Finance – Used Cars" } ], "makes_list": [ { "id": 90, "name": "Toyota", "logo": "https://s3.eu-central-1.amazonaws.com/v3-common.motory.com/taxonomy/l-1669878465.8496-638852c1cf6f3.webp" } ] }, "pagination": { "page": 1, "page_size": 20, "total_items": 20, "total_pages": 1 } } } } } }, "400": { "description": "Bad request — a parameter is missing, malformed or out of range", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MotoryErrorResponseSchema" } } } }, "404": { "description": "Not found — the requested id or link does not exist", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MotoryErrorResponseSchema" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MotoryErrorResponseSchema" } } } }, "503": { "description": "Service busy — retry shortly", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MotoryErrorResponseSchema" } } } } } } }, "/dealer-details": { "get": { "tags": [ "Dealers" ], "operationId": "getDealerDetails", "description": "Read one dealer's profile: phones, WhatsApp, showroom map locations, branch count and stock count. Takes a dealer_id from /dealers; list the dealer's cars with /used-cars?dealer_id=.", "parameters": [ { "schema": { "type": "integer", "description": "**Dealer id.** Required; for example `454541` (Saudi Arabia).\n\nTake `dealer_id` from a `/dealers` row, or `seller_id` from a `/used-cars` row of a dealer listing, fetched with the same `country`. An unknown id, or an id from the other market, returns 404.", "minimum": 1, "example": 454541 }, "required": true, "description": "**Dealer id.** Required; for example `454541` (Saudi Arabia).\n\nTake `dealer_id` from a `/dealers` row, or `seller_id` from a `/used-cars` row of a dealer listing, fetched with the same `country`. An unknown id, or an id from the other market, returns 404.", "name": "dealer_id", "in": "query" }, { "schema": { "type": "string", "description": "**Market to read.** Optional; defaults to `sa`.\n\n- `sa` — Saudi Arabia (prices in SAR)\n- `jo` — Jordan (prices in JOD)\n\nEach market has its own inventory and its own ids (makes, models, cities, body types, dealers, vehicles). Send only ids from a call made with the same `country`. An id from the other market is answered as an unknown id:\n\n- **404** — a lookup by id: every details route, `/models`, `/finance-providers`, and `category_id` on `/category-news` and `/videos`.\n- **400 naming the param** — `make_id`, `model_id` and `finance_provider_id` on `/new-cars` and `/new-car-filters`; `make_id` and `city_id` on `/dealers`; `make_id` and `company_id` on `/offers`; `make_id`, `author_id` and `category_id` as filters of the news lists, and `make_id` on `/videos` (on `/tag-news`, an unknown `author_id` with a tag that is not a make returns an empty list when the tag has articles in the requested `lang`, and 404 otherwise).\n- **Empty result** — every other id filter, for example `body_type_id`, `fuel_type_id`, `transmission_id` or `origin_id` on `/new-cars`, every `/used-cars` and `/used-car-filters` filter, and `dealer_id` on `/dealers`.", "enum": [ "sa", "jo" ], "default": "sa" }, "required": false, "description": "**Market to read.** Optional; defaults to `sa`.\n\n- `sa` — Saudi Arabia (prices in SAR)\n- `jo` — Jordan (prices in JOD)\n\nEach market has its own inventory and its own ids (makes, models, cities, body types, dealers, vehicles). Send only ids from a call made with the same `country`. An id from the other market is answered as an unknown id:\n\n- **404** — a lookup by id: every details route, `/models`, `/finance-providers`, and `category_id` on `/category-news` and `/videos`.\n- **400 naming the param** — `make_id`, `model_id` and `finance_provider_id` on `/new-cars` and `/new-car-filters`; `make_id` and `city_id` on `/dealers`; `make_id` and `company_id` on `/offers`; `make_id`, `author_id` and `category_id` as filters of the news lists, and `make_id` on `/videos` (on `/tag-news`, an unknown `author_id` with a tag that is not a make returns an empty list when the tag has articles in the requested `lang`, and 404 otherwise).\n- **Empty result** — every other id filter, for example `body_type_id`, `fuel_type_id`, `transmission_id` or `origin_id` on `/new-cars`, every `/used-cars` and `/used-car-filters` filter, and `dealer_id` on `/dealers`.", "name": "country", "in": "query" }, { "schema": { "type": "string", "description": "**Response language.** Optional; defaults to `en`.\n\n- `en` — English\n- `ar` — Arabic\n\nChanges labels, titles and descriptions only; ids and numeric values are the same in both languages.", "enum": [ "en", "ar" ], "default": "en" }, "required": false, "description": "**Response language.** Optional; defaults to `en`.\n\n- `en` — English\n- `ar` — Arabic\n\nChanges labels, titles and descriptions only; ids and numeric values are the same in both languages.", "name": "lang", "in": "query" } ], "responses": { "200": { "description": "**One dealer's profile.**\n\n- `dealer_name`, `package_tag`, `body` (profile text), `image`, `city` and `is_featured`.\n- `vehicles_count` (cars listed, as a string) and `vehicle_type`.\n- Published `phone_numbers` and `whatsapp_number`, with `enable_whatsapp_phone` flags.\n- `locations_list` (named showroom locations with map links), `branches_count` and the public `share_link`.\n\nThe profile carries no cars: list the dealer's stock with `/used-cars?dealer_id=`. A dealer with nothing currently listed still returns its profile (`vehicles_count` \"0\"). Unknown ids return 404.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MotorySuccessResponseSchema" }, "example": { "success": true, "data": { "dealer_id": 454541, "vehicles_count": "215", "dealer_name": "Shop By Motory", "package_tag": "VIP", "body": "A secure online store and an authorized dealer for several car dealerships in the kingdom. Shop By Motory offers various types of new cars at competitive prices, ensuring safe sales and unique after-sales services.\r\n\r\nShop By Motory is one of the investments of Abdul Latif Jameel Technology Company.", "image": "https://s3.eu-central-1.amazonaws.com/v3-companies.motory.com/dealer/l-1698915852.7377-6543660cb41b6.webp", "city": "All Cities", "is_featured": true, "phone_numbers": [ { "phone": "+966920004179", "phone_name": "Shop By Motory" } ], "whatsapp_number": "+966920004179", "enable_whatsapp_phone": { "enable_whats_app": true, "enable_phone": true }, "locations_list": [ { "location_name": "Shop By Motory Center", "location_link": "https://maps.app.goo.gl/n1NUuQN7ftfZQ4FX9" } ], "branches_count": 2, "vehicle_type": "New & Used", "tooltip": null, "share_link": "https://ksa.motory.com/en/cars-dealers/riyadh/shop-by-motory-454541/" } } } } }, "400": { "description": "Bad request — a parameter is missing, malformed or out of range", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MotoryErrorResponseSchema" } } } }, "404": { "description": "Not found — the requested id or link does not exist", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MotoryErrorResponseSchema" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MotoryErrorResponseSchema" } } } }, "503": { "description": "Service busy — retry shortly", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MotoryErrorResponseSchema" } } } } } } }, "/offers": { "get": { "tags": [ "Offers" ], "operationId": "listCarOffers", "description": "List current car offers and financing deals published by distributors and dealers, optionally for one make or one offering company. Take ids from /makes or the filter_lists; open an offer id in /offer-details.", "parameters": [ { "schema": { "type": "string", "description": "**Market to read.** Optional; defaults to `sa`.\n\n- `sa` — Saudi Arabia (prices in SAR)\n- `jo` — Jordan (prices in JOD)\n\nEach market has its own inventory and its own ids (makes, models, cities, body types, dealers, vehicles). Send only ids from a call made with the same `country`. An id from the other market is answered as an unknown id:\n\n- **404** — a lookup by id: every details route, `/models`, `/finance-providers`, and `category_id` on `/category-news` and `/videos`.\n- **400 naming the param** — `make_id`, `model_id` and `finance_provider_id` on `/new-cars` and `/new-car-filters`; `make_id` and `city_id` on `/dealers`; `make_id` and `company_id` on `/offers`; `make_id`, `author_id` and `category_id` as filters of the news lists, and `make_id` on `/videos` (on `/tag-news`, an unknown `author_id` with a tag that is not a make returns an empty list when the tag has articles in the requested `lang`, and 404 otherwise).\n- **Empty result** — every other id filter, for example `body_type_id`, `fuel_type_id`, `transmission_id` or `origin_id` on `/new-cars`, every `/used-cars` and `/used-car-filters` filter, and `dealer_id` on `/dealers`.", "enum": [ "sa", "jo" ], "default": "sa" }, "required": false, "description": "**Market to read.** Optional; defaults to `sa`.\n\n- `sa` — Saudi Arabia (prices in SAR)\n- `jo` — Jordan (prices in JOD)\n\nEach market has its own inventory and its own ids (makes, models, cities, body types, dealers, vehicles). Send only ids from a call made with the same `country`. An id from the other market is answered as an unknown id:\n\n- **404** — a lookup by id: every details route, `/models`, `/finance-providers`, and `category_id` on `/category-news` and `/videos`.\n- **400 naming the param** — `make_id`, `model_id` and `finance_provider_id` on `/new-cars` and `/new-car-filters`; `make_id` and `city_id` on `/dealers`; `make_id` and `company_id` on `/offers`; `make_id`, `author_id` and `category_id` as filters of the news lists, and `make_id` on `/videos` (on `/tag-news`, an unknown `author_id` with a tag that is not a make returns an empty list when the tag has articles in the requested `lang`, and 404 otherwise).\n- **Empty result** — every other id filter, for example `body_type_id`, `fuel_type_id`, `transmission_id` or `origin_id` on `/new-cars`, every `/used-cars` and `/used-car-filters` filter, and `dealer_id` on `/dealers`.", "name": "country", "in": "query" }, { "schema": { "type": "string", "description": "**Response language.** Optional; defaults to `en`.\n\n- `en` — English\n- `ar` — Arabic\n\nChanges labels, titles and descriptions only; ids and numeric values are the same in both languages.", "enum": [ "en", "ar" ], "default": "en" }, "required": false, "description": "**Response language.** Optional; defaults to `en`.\n\n- `en` — English\n- `ar` — Arabic\n\nChanges labels, titles and descriptions only; ids and numeric values are the same in both languages.", "name": "lang", "in": "query" }, { "schema": { "type": "integer", "description": "**Only offers covering this make.** Optional; one make id (for example `90`).\n\nTake ids from `filter_lists.makes_list` of this endpoint (makes with offers) or from `/makes`, called with the same `country`. A make with no current offer returns an empty list; an id the market does not know is rejected with 400. One value only — a comma-separated list is rejected with 400.", "minimum": 1 }, "required": false, "description": "**Only offers covering this make.** Optional; one make id (for example `90`).\n\nTake ids from `filter_lists.makes_list` of this endpoint (makes with offers) or from `/makes`, called with the same `country`. A make with no current offer returns an empty list; an id the market does not know is rejected with 400. One value only — a comma-separated list is rejected with 400.", "name": "make_id", "in": "query" }, { "schema": { "type": "integer", "description": "**Only offers from this company.** Optional; one offer-company id.\n\nOffer companies (distributors and dealers publishing offers) have their own ids: take them from `filter_lists.companies_list` of this endpoint or a row's `company.id`, called with the same `country`. An id the market does not know is rejected with 400. One value only.", "minimum": 1 }, "required": false, "description": "**Only offers from this company.** Optional; one offer-company id.\n\nOffer companies (distributors and dealers publishing offers) have their own ids: take them from `filter_lists.companies_list` of this endpoint or a row's `company.id`, called with the same `country`. An id the market does not know is rejected with 400. One value only.", "name": "company_id", "in": "query" }, { "schema": { "type": "integer", "description": "**Page number, starting at 1.** Optional; defaults to `1`.\n\nKeep `page_size` fixed while paging and stop at `pagination.total_pages`. A `page` beyond the last page returns an empty `items` list.", "minimum": 1, "maximum": 10000, "default": 1 }, "required": false, "description": "**Page number, starting at 1.** Optional; defaults to `1`.\n\nKeep `page_size` fixed while paging and stop at `pagination.total_pages`. A `page` beyond the last page returns an empty `items` list.", "name": "page", "in": "query" }, { "schema": { "type": "integer", "description": "**Results per page.** Optional; defaults to `20`, accepts 1–50.\n\nValues above 50 are rejected with 400. Keep the same `page_size` on every page of one search so pages neither overlap nor skip results.", "minimum": 1, "maximum": 50, "default": 20 }, "required": false, "description": "**Results per page.** Optional; defaults to `20`, accepts 1–50.\n\nValues above 50 are rejected with 400. Keep the same `page_size` on every page of one search so pages neither overlap nor skip results.", "name": "page_size", "in": "query" } ], "responses": { "200": { "description": "**Current car offers** (financing deals, purchase promotions) published by distributors and dealers, optionally narrowed to one make or one offering company.\n\nEach row is an offer card as served:\n\n- `id`, `title`, `offer_url`, `image` and `benefits`.\n- `offer_start` / `offer_end` (`DD/MM/YYYY` as served) and `expiry_days_left`.\n- `make` (make and company names and logos) and `makes_list` (makes the offer covers, with ids).\n- `company` — `id`, name and logo.\n\nRelated data:\n\n- Read an offer with `/offer-details` for the cars on offer and their prices, instalments and down payments.\n- `filter_lists` — the makes and companies this list can be filtered by; the only source of `company_id` values.\n- `pagination.total_items` counts every matching offer; a `page` past `pagination.total_pages` returns an empty `items` list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MotorySuccessResponseSchema" }, "example": { "success": true, "data": { "items": [ { "id": 4842, "title": "Own the 2026 Lexus NX Now – Exclusive Offers with Bank AlJazira ", "offer_url": "https://ksa.motory.com/en/cars-offers/own-the-2026-lexus-nx-now-exclusive-offers-with-bank-aljazira-4842/", "offer_start": "11/10/2026", "offer_end": "31/10/2026", "offer_without_date": null, "image": "https://s3.eu-central-1.amazonaws.com/v3-car-offer.motory.com/car-offer/l-1791805184.4651-6accc700718d2.webp", "make": { "make_name": "Lexus", "make_logo": "https://s3.eu-central-1.amazonaws.com/v3-common.motory.com/taxonomy/60x60/l-1669878562.1772-638853222b444.webp", "company_name": "Abdul Latif Jameel Motors - Lexus", "company_logo": "https://s3.eu-central-1.amazonaws.com/v3-companies.motory.com/company/l-1787489649.9755-6a8aed71ee298.webp" }, "makes_count": 0, "makes_list": [ { "id": 74, "image": "https://s3.eu-central-1.amazonaws.com/v3-common.motory.com/taxonomy/60x60/l-1669878562.1772-638853222b444.webp", "name": "Lexus" } ], "company": { "id": 18, "is_company": true, "name": "Abdul Latif Jameel Motors - Lexus", "image": "https://s3.eu-central-1.amazonaws.com/v3-companies.motory.com/company/l-1787489649.9755-6a8aed71ee298.webp" }, "expiry_days_left": 20, "benefits": [], "breadcrumb_urls": null } ], "filter_lists": { "makes_list": [ { "id": 90, "name": "Toyota", "logo": "https://s3.eu-central-1.amazonaws.com/v3-common.motory.com/taxonomy/l-1669878465.8496-638852c1cf6f3.webp", "slug_ar": "تويوتا", "slug_en": "toyota" } ], "companies_list": [ { "id": 90, "name": "ALJABR - JMC", "logo": "https://s3.eu-central-1.amazonaws.com/v3-companies.motory.com/company/l-1690197361.2041-64be5d7131d52.webp", "slug_ar": "عروض-الجبر-جيه-ام-سي", "slug_en": "aljabr-jmc-offers" } ], "selected_item": [] }, "pagination": { "page": 1, "page_size": 20, "total_items": 76, "total_pages": 4 } } } } } }, "400": { "description": "Bad request — a parameter is missing, malformed or out of range", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MotoryErrorResponseSchema" } } } }, "404": { "description": "Not found — the requested id or link does not exist", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MotoryErrorResponseSchema" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MotoryErrorResponseSchema" } } } }, "503": { "description": "Service busy — retry shortly", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MotoryErrorResponseSchema" } } } } } } }, "/offer-details": { "get": { "tags": [ "Offers" ], "operationId": "getCarOfferDetails", "description": "Read one car offer: terms, start and end dates, the offering company, the cars on offer with monthly instalment and down payment, and the eligibility terms an application-form offer states. Takes an offer_id, the id of an /offers row.", "parameters": [ { "schema": { "type": "integer", "description": "**Offer id.** Required; for example `4822` (Saudi Arabia).\n\nTake `id` from an `/offers` row (or an `offers` item of /new-car-details or /used-car-details) fetched with the same `country`. An offer no longer listed in `/offers`, an unknown id, or an id from the other market returns 404.", "minimum": 1, "example": 4822 }, "required": true, "description": "**Offer id.** Required; for example `4822` (Saudi Arabia).\n\nTake `id` from an `/offers` row (or an `offers` item of /new-car-details or /used-car-details) fetched with the same `country`. An offer no longer listed in `/offers`, an unknown id, or an id from the other market returns 404.", "name": "offer_id", "in": "query" }, { "schema": { "type": "string", "description": "**Market to read.** Optional; defaults to `sa`.\n\n- `sa` — Saudi Arabia (prices in SAR)\n- `jo` — Jordan (prices in JOD)\n\nEach market has its own inventory and its own ids (makes, models, cities, body types, dealers, vehicles). Send only ids from a call made with the same `country`. An id from the other market is answered as an unknown id:\n\n- **404** — a lookup by id: every details route, `/models`, `/finance-providers`, and `category_id` on `/category-news` and `/videos`.\n- **400 naming the param** — `make_id`, `model_id` and `finance_provider_id` on `/new-cars` and `/new-car-filters`; `make_id` and `city_id` on `/dealers`; `make_id` and `company_id` on `/offers`; `make_id`, `author_id` and `category_id` as filters of the news lists, and `make_id` on `/videos` (on `/tag-news`, an unknown `author_id` with a tag that is not a make returns an empty list when the tag has articles in the requested `lang`, and 404 otherwise).\n- **Empty result** — every other id filter, for example `body_type_id`, `fuel_type_id`, `transmission_id` or `origin_id` on `/new-cars`, every `/used-cars` and `/used-car-filters` filter, and `dealer_id` on `/dealers`.", "enum": [ "sa", "jo" ], "default": "sa" }, "required": false, "description": "**Market to read.** Optional; defaults to `sa`.\n\n- `sa` — Saudi Arabia (prices in SAR)\n- `jo` — Jordan (prices in JOD)\n\nEach market has its own inventory and its own ids (makes, models, cities, body types, dealers, vehicles). Send only ids from a call made with the same `country`. An id from the other market is answered as an unknown id:\n\n- **404** — a lookup by id: every details route, `/models`, `/finance-providers`, and `category_id` on `/category-news` and `/videos`.\n- **400 naming the param** — `make_id`, `model_id` and `finance_provider_id` on `/new-cars` and `/new-car-filters`; `make_id` and `city_id` on `/dealers`; `make_id` and `company_id` on `/offers`; `make_id`, `author_id` and `category_id` as filters of the news lists, and `make_id` on `/videos` (on `/tag-news`, an unknown `author_id` with a tag that is not a make returns an empty list when the tag has articles in the requested `lang`, and 404 otherwise).\n- **Empty result** — every other id filter, for example `body_type_id`, `fuel_type_id`, `transmission_id` or `origin_id` on `/new-cars`, every `/used-cars` and `/used-car-filters` filter, and `dealer_id` on `/dealers`.", "name": "country", "in": "query" }, { "schema": { "type": "string", "description": "**Response language.** Optional; defaults to `en`.\n\n- `en` — English\n- `ar` — Arabic\n\nChanges labels, titles and descriptions only; ids and numeric values are the same in both languages.", "enum": [ "en", "ar" ], "default": "en" }, "required": false, "description": "**Response language.** Optional; defaults to `en`.\n\n- `en` — English\n- `ar` — Arabic\n\nChanges labels, titles and descriptions only; ids and numeric values are the same in both languages.", "name": "lang", "in": "query" } ], "responses": { "200": { "description": "**One car offer**: its record, the cars on offer and, for application-form offers, the eligibility terms.\n\n- `offer` — the offer record: `offer_application_type` (finance / purchase / form_only), title, start and end dates, `description`, `disclaimer`, makes covered, offering `company`, `share_link` and `expiry_days_left`.\n- `vehicles` — the cars on offer. Each row carries the car `title`, image, fuel / engine / horsepower lines, `offer_price_object` (cash prices, monthly instalment with period, down payment), `application_type`, the company phone and `vehicle_new_id` (when not null, read that car with `/new-car-details?vehicle_id=`). Offers without a car list return `vehicles: []`.\n- `eligibility` — the terms an application-form offer (`offer_application_type` form_only) states through its form, each list exactly as the offer publishes it (ids and texts): `makes`, `models` and `years` covered, eligible `cities`, `branches`, `payment_types` (cash / finance), `purchase_horizons` (how soon the buyer plans to buy) and `min_monthly_income` (the applicant's minimum monthly income, market currency). A term the offer does not state is null; offers without such a form return `eligibility: null`.\n\nUnknown ids, and offers no longer listed, return 404.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MotorySuccessResponseSchema" }, "examples": { "finance_offer": { "summary": "Finance offer with its cars", "description": "Response to `/offer-details?offer_id=4822`: a finance offer that lists its cars in `vehicles`. It has no application form, so `eligibility` is null.", "value": { "success": true, "data": { "offer": { "id": 4822, "offer_application_type": "finance", "title": "Honda CR‑V Offers Now Live at Abdulla Hashim", "offer_start": "08/10/2026", "offer_end": "31/10/2026", "offer_without_date": null, "image": "https://s3.eu-central-1.amazonaws.com/v3-car-offer.motory.com/car-offer/l-1791443800.9291-6ac74358e2d28.webp", "images": null, "disclaimer": { "title": "Important Disclaimer Regarding Pricing & Financing", "description": "Retail prices are not inclusive of VAT unless stated otherwise. All of the details provided in this page including the price and monthly payment are indicative, and could change at any moment. Please contact the local dealership or financing provider for more accurate details. Displayed photos are shown for illustration purposes only and might not represent this specific trim/grade." }, "make": { "make_name": "Honda", "make_logo": "https://s3.eu-central-1.amazonaws.com/v3-common.motory.com/taxonomy/60x60/l-1669878739.0935-638853d316d5e.webp", "company_name": "Abdullah Hashim Co", "company_logo": "https://s3.eu-central-1.amazonaws.com/v3-companies.motory.com/company/l-1783251012.2252-6a4a404436fd4.webp" }, "makes_count": 0, "makes_list": [ { "id": 63, "image": "https://s3.eu-central-1.amazonaws.com/v3-common.motory.com/taxonomy/60x60/l-1669878739.0935-638853d316d5e.webp", "name": "Honda" } ], "description": "A new offer has been launched by Abdullah Hashim Co for Honda 2025 cars in Saudi Arabia on 08/10/2026 and will end on 31/10/2026. The cars included in the offer are Honda CR-V 2025 DX. You can view the phone number of Abdullah Hashim Co or call the company directly if you're using your mobile device to inquire about this offer.\r\nFinancing is provided by Abdullah Hashim Co., and you can choose the car most suitable for you, fill out the finance application form, then submit your application and Motory will deliver it directly to Abdullah Hashim Co and Abdullah Hashim Co., who will contact you the soonest possible to process your request and take you forward.", "company": { "id": 6, "is_company": true, "name": "Abdullah Hashim Co", "image": "https://s3.eu-central-1.amazonaws.com/v3-companies.motory.com/company/l-1783251012.2252-6a4a404436fd4.webp", "name_gtm_label": "Abdullah Hashim Co" }, "share_link": "https://ksa.motory.com/en/cars-offers/honda-crv-offers-now-live-at-abdulla-hashim-4822/", "expiry_days_left": 20, "benefits": [], "breadcrumb_urls": null }, "vehicles": [ { "id": 8302, "vehicle_new_id": 260690, "has_details": true, "image": "https://s3.eu-central-1.amazonaws.com/v3-car-offer.motory.com/car-offer-vehicle/l-1791443778.1049-6ac74342199f6.webp", "title": "Honda CR-V 2025 DX", "make_logo": "https://s3.eu-central-1.amazonaws.com/v3-common.motory.com/taxonomy/l-1669878739.0935-638853d316d5e.webp", "fuel_data": "Fuel : 15.5 Km/L", "engine_data": "Engine : 1.5 L", "horsepower_data": "Horsepower : 190 hp", "offer_price_object": { "price1_text": null, "price1_value": null, "price2_text": null, "price2_value": null, "show_deleted_price": false, "price_currency": null, "monthly_payment_text": "Installment from / Period", "monthly_payment_value": "1,499", "monthly_payment_currency": "SR", "monthly_payment_period": "60 Months", "down_payment_text": "Down Payment", "down_payment_value": "0%", "down_payment_currency": null }, "application_type": "finance", "apply_button": "Finance", "call_button": "Call Company", "company_phone": "920002208", "make_gtm_label": "Honda", "model_gtm_label": "CR-V", "year_gtm_label": 2025 } ], "eligibility": null } } }, "form_only_offer": { "summary": "Application-form offer with its eligibility terms", "description": "Response to `/offer-details?offer_id=4399`: an application-form offer (`offer_application_type` form_only). It lists no cars (`vehicles: []`) and states its terms in `eligibility`.", "value": { "success": true, "data": { "offer": { "id": 4399, "offer_application_type": "form_only", "title": "JMC Car Offers: 0% Profit Rate For 18 Months", "offer_start": "05/07/2026", "offer_end": "31/12/2026", "offer_without_date": null, "image": "https://s3.eu-central-1.amazonaws.com/v3-car-offer.motory.com/car-offer/l-1783321797.681-6a4b54c5a6404.webp", "images": null, "disclaimer": { "title": "Important Disclaimer Regarding Pricing & Financing", "description": "Retail prices are not inclusive of VAT unless stated otherwise. All of the details provided in this page including the price and monthly payment are indicative, and could change at any moment. Please contact the local dealership or financing provider for more accurate details. Displayed photos are shown for illustration purposes only and might not represent this specific trim/grade." }, "make": { "make_name": "JMC", "make_logo": "https://s3.eu-central-1.amazonaws.com/v3-common.motory.com/taxonomy/l-1605478981.8521-5fb1aa45d0078.webp", "company_name": "ALJABR - JMC", "company_logo": "https://s3.eu-central-1.amazonaws.com/v3-companies.motory.com/company/l-1690197361.2041-64be5d7131d52.webp" }, "makes_count": 0, "makes_list": [ { "id": 739, "image": "https://s3.eu-central-1.amazonaws.com/v3-common.motory.com/taxonomy/l-1605478981.8521-5fb1aa45d0078.webp", "name": "JMC" } ], "description": "A new offer has been launched by ALJABR - JMC for JMC cars in Saudi Arabia on 05/07/2026 and will end on 31/12/2026. You can apply for the offer by filling out the offer application form, then submit your application and Motory will deliver it directly to ALJABR - JMC, who will contact you the soonest possible to process your request and take you forward.", "company": { "id": 90, "is_company": true, "name": "ALJABR - JMC", "image": "https://s3.eu-central-1.amazonaws.com/v3-companies.motory.com/company/l-1690197361.2041-64be5d7131d52.webp", "name_gtm_label": "ALJABR - JMC" }, "share_link": "https://ksa.motory.com/en/cars-offers/jmc-car-offers-0-profit-rate-for-18-months-4399/", "expiry_days_left": 81, "benefits": [], "breadcrumb_urls": null }, "vehicles": [], "eligibility": { "makes": [ { "id": 739, "text": "JMC", "logo": "https://s3.eu-central-1.amazonaws.com/v3-common.motory.com/taxonomy/l-1605478981.8521-5fb1aa45d0078.webp" } ], "models": [ { "id": 1577, "text": "Vigus" } ], "years": null, "cities": [ { "id": 805, "text": "Al Kharj", "nested_list": [], "show_component": null, "hide_component": [ "branch_id" ] }, { "id": 810, "text": "Riyadh", "nested_list": [ { "id": 1314, "text": "Riyadh - Al Qadisiyyah" } ], "show_component": [ "branch_id" ], "hide_component": null } ], "branches": null, "payment_types": null, "purchase_horizons": [ { "id": 2849, "text": "Immediate" } ], "min_monthly_income": 4000 } } } } } } } }, "400": { "description": "Bad request — a parameter is missing, malformed or out of range", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MotoryErrorResponseSchema" } } } }, "404": { "description": "Not found — the requested id or link does not exist", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MotoryErrorResponseSchema" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MotoryErrorResponseSchema" } } } }, "503": { "description": "Service busy — retry shortly", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MotoryErrorResponseSchema" } } } } } } }, "/directory-search": { "get": { "tags": [ "Directory" ], "operationId": "searchDirectory", "description": "Search Saudi automotive businesses and companies by name, address, city, make served, service, amenity, opening day, open now, provider kind and agent flag. Take ids from /directory-cities, /directory-makes, /directory-services and /directory-amenities.", "parameters": [ { "schema": { "type": "string", "description": "**Provider name.** Optional; English or Arabic, case-insensitive (for example `ehsan`, `spare parts` or `قطع غيار`).\n\nMatches names that contain the text as written, letters and digits in that order:\n\n- Spaces and hyphens are interchangeable: `al baridi` finds \"Al-Baridi Vehicle Inspection Center\".\n- Other punctuation is ignored: `drmftcars` or `dr.mft.cars` finds \"Dr.MFT.Cars\".\n- Accents are ignored: `e` also finds \"é\".\n- The text can start or stop mid-word: `a` matches every name with an \"a\".\n- Businesses and companies both match. A company name also matches with its punctuation typed as spaces: `s m a al suhaimi` finds \"S.M.A Al Suhaimi For Tyres EST\".\n- A business is found through the name its `link` spells. When several businesses share a name, the `link` of the later ones ends in a number (`-2`, `-3`), so a digit can also find a business whose name has no digit.\n\nFor companies only, `/directory-companies` also takes `name`.", "maxLength": 100 }, "required": false, "description": "**Provider name.** Optional; English or Arabic, case-insensitive (for example `ehsan`, `spare parts` or `قطع غيار`).\n\nMatches names that contain the text as written, letters and digits in that order:\n\n- Spaces and hyphens are interchangeable: `al baridi` finds \"Al-Baridi Vehicle Inspection Center\".\n- Other punctuation is ignored: `drmftcars` or `dr.mft.cars` finds \"Dr.MFT.Cars\".\n- Accents are ignored: `e` also finds \"é\".\n- The text can start or stop mid-word: `a` matches every name with an \"a\".\n- Businesses and companies both match. A company name also matches with its punctuation typed as spaces: `s m a al suhaimi` finds \"S.M.A Al Suhaimi For Tyres EST\".\n- A business is found through the name its `link` spells. When several businesses share a name, the `link` of the later ones ends in a number (`-2`, `-3`), so a digit can also find a business whose name has no digit.\n\nFor companies only, `/directory-companies` also takes `name`.", "name": "name", "in": "query" }, { "schema": { "type": "string", "description": "**Address text.** Optional; English or Arabic, case-insensitive substring of the address (for example a district or street name such as `King Fahd` or `الملك فهد`).\n\nA company matches when one of its branches' addresses contains the text. Spelling follows the provider's own address, so try both languages; use `city_id` to filter by city.", "maxLength": 100 }, "required": false, "description": "**Address text.** Optional; English or Arabic, case-insensitive substring of the address (for example a district or street name such as `King Fahd` or `الملك فهد`).\n\nA company matches when one of its branches' addresses contains the text. Spelling follows the provider's own address, so try both languages; use `city_id` to filter by city.", "name": "address", "in": "query" }, { "schema": { "type": "string", "description": "**City filter.** Optional; one or more city ids, comma-separated (for example `810,821`); any listed city matches.\n\nTake ids from `/directory-cities`. A company matches when any of its branches is in the city." }, "required": false, "description": "**City filter.** Optional; one or more city ids, comma-separated (for example `810,821`); any listed city matches.\n\nTake ids from `/directory-cities`. A company matches when any of its branches is in the city.", "name": "city_id", "in": "query" }, { "schema": { "type": "string", "description": "**Car make served.** Optional; one or more make ids, comma-separated; any listed make matches.\n\nTake ids from `/directory-makes`. Matches providers whose published list of makes includes a listed make. Providers that serve every make publish the list of makes as it stood when they joined the directory, so a make added to the directory since (a recently launched brand) does not match them here; `/directory-branches` with `make_id` does count the branches that serve every make (`is_all_make: true`)." }, "required": false, "description": "**Car make served.** Optional; one or more make ids, comma-separated; any listed make matches.\n\nTake ids from `/directory-makes`. Matches providers whose published list of makes includes a listed make. Providers that serve every make publish the list of makes as it stood when they joined the directory, so a make added to the directory since (a recently launched brand) does not match them here; `/directory-branches` with `make_id` does count the branches that serve every make (`is_all_make: true`).", "name": "make_id", "in": "query" }, { "schema": { "type": "string", "description": "**Service offered** (spare parts, car wash, tyres, inspection…). Optional; one or more service ids, comma-separated; any listed service matches.\n\nTake ids from `/directory-services`." }, "required": false, "description": "**Service offered** (spare parts, car wash, tyres, inspection…). Optional; one or more service ids, comma-separated; any listed service matches.\n\nTake ids from `/directory-services`.", "name": "service_id", "in": "query" }, { "schema": { "type": "string", "description": "**Amenity offered** (parking, waiting area, card payment…). Optional; one or more amenity ids, comma-separated; any listed amenity matches.\n\nTake ids from `/directory-amenities`." }, "required": false, "description": "**Amenity offered** (parking, waiting area, card payment…). Optional; one or more amenity ids, comma-separated; any listed amenity matches.\n\nTake ids from `/directory-amenities`.", "name": "amenity_id", "in": "query" }, { "schema": { "type": "string", "description": "**Open on this weekday.** Optional; keeps providers with opening hours on that day.\n\n- `sunday` — Sunday\n- `monday` — Monday\n- `tuesday` — Tuesday\n- `wednesday` — Wednesday\n- `thursday` — Thursday\n- `friday` — Friday\n- `saturday` — Saturday\n\nA company matches when one of its branches has opening hours that day.", "enum": [ "sunday", "monday", "tuesday", "wednesday", "thursday", "friday", "saturday" ] }, "required": false, "description": "**Open on this weekday.** Optional; keeps providers with opening hours on that day.\n\n- `sunday` — Sunday\n- `monday` — Monday\n- `tuesday` — Tuesday\n- `wednesday` — Wednesday\n- `thursday` — Thursday\n- `friday` — Friday\n- `saturday` — Saturday\n\nA company matches when one of its branches has opening hours that day.", "name": "day", "in": "query" }, { "schema": { "type": "boolean", "description": "**Only providers that Motory lists as open right now** (Saudi Arabia time). Optional.\n\n- `true` — keep only providers that Motory lists as open at the current time\n- omitted — providers whatever their opening state\n\n`false` is rejected with 400: there is no \"closed now\" filter. `open_now` already means today, so it combines with `day` only when `day` is today's weekday in Saudi Arabia; any other `day` returns 400.\n\n- Motory does not count opening hours that end at or after midnight (for example `08:00 AM–12:00 AM` or `07:00 AM–01:00 AM`) as open, so providers with such hours are missing even while they are open. For a company's branches use `/directory-branches?open_now=true`, which counts those hours.\n- A company counts as open when one of its branches is open; with `city_id`, that open branch must be in a listed city (a company open in one city is not returned for another city where its branches are closed).", "example": "" }, "required": false, "description": "**Only providers that Motory lists as open right now** (Saudi Arabia time). Optional.\n\n- `true` — keep only providers that Motory lists as open at the current time\n- omitted — providers whatever their opening state\n\n`false` is rejected with 400: there is no \"closed now\" filter. `open_now` already means today, so it combines with `day` only when `day` is today's weekday in Saudi Arabia; any other `day` returns 400.\n\n- Motory does not count opening hours that end at or after midnight (for example `08:00 AM–12:00 AM` or `07:00 AM–01:00 AM`) as open, so providers with such hours are missing even while they are open. For a company's branches use `/directory-branches?open_now=true`, which counts those hours.\n- A company counts as open when one of its branches is open; with `city_id`, that open branch must be in a listed city (a company open in one city is not returned for another city where its branches are closed).", "name": "open_now", "in": "query" }, { "schema": { "type": "string", "description": "**Provider kind.** Optional; omitted returns both.\n\n- `business` — business listings (read one with `/directory-business-details`)\n- `company` — multi-branch companies (read one with `/directory-company-details`, its locations with `/directory-branches`)", "enum": [ "business", "company" ] }, "required": false, "description": "**Provider kind.** Optional; omitted returns both.\n\n- `business` — business listings (read one with `/directory-business-details`)\n- `company` — multi-branch companies (read one with `/directory-company-details`, its locations with `/directory-branches`)", "name": "provider_type", "in": "query" }, { "schema": { "type": "boolean", "description": "**Official agents.** Optional.\n\n- `true` — only providers flagged `is_agent: true`\n- `false` — only providers not flagged as agents\n- omitted — both", "example": "" }, "required": false, "description": "**Official agents.** Optional.\n\n- `true` — only providers flagged `is_agent: true`\n- `false` — only providers not flagged as agents\n- omitted — both", "name": "is_agent", "in": "query" }, { "schema": { "type": "string", "description": "**Result order.** Optional; defaults to `newest`.\n\n- `newest` — most recently added first\n- `oldest` — earliest added first\n- `name_asc` — name A→Z (Arabic names when `lang=ar`)\n- `name_desc` — name Z→A\n\nUnder the name orders, companies are grouped before businesses (`name_asc`) or after them (`name_desc`) and are not alphabetised among themselves; with `provider_type=company` they are alphabetised.", "enum": [ "newest", "oldest", "name_asc", "name_desc" ], "default": "newest" }, "required": false, "description": "**Result order.** Optional; defaults to `newest`.\n\n- `newest` — most recently added first\n- `oldest` — earliest added first\n- `name_asc` — name A→Z (Arabic names when `lang=ar`)\n- `name_desc` — name Z→A\n\nUnder the name orders, companies are grouped before businesses (`name_asc`) or after them (`name_desc`) and are not alphabetised among themselves; with `provider_type=company` they are alphabetised.", "name": "sort", "in": "query" }, { "schema": { "type": "string", "description": "**Response language.** Optional; defaults to `en`.\n\n- `en` — English\n- `ar` — Arabic\n\nChanges labels, titles and descriptions only; ids and numeric values are the same in both languages.", "enum": [ "en", "ar" ], "default": "en" }, "required": false, "description": "**Response language.** Optional; defaults to `en`.\n\n- `en` — English\n- `ar` — Arabic\n\nChanges labels, titles and descriptions only; ids and numeric values are the same in both languages.", "name": "lang", "in": "query" }, { "schema": { "type": "integer", "description": "**Page number, starting at 1.** Optional; defaults to `1`.\n\nKeep `page_size` fixed while paging and stop at `pagination.total_pages`. A `page` beyond the last page returns an empty `items` list.", "minimum": 1, "maximum": 10000, "default": 1 }, "required": false, "description": "**Page number, starting at 1.** Optional; defaults to `1`.\n\nKeep `page_size` fixed while paging and stop at `pagination.total_pages`. A `page` beyond the last page returns an empty `items` list.", "name": "page", "in": "query" }, { "schema": { "type": "integer", "description": "**Results per page.** Optional; defaults to `20`, accepts 1–200.\n\nValues above 200 are rejected with 400. Keep the same `page_size` on every page of one search so pages neither overlap nor skip results.", "minimum": 1, "maximum": 200, "default": 20 }, "required": false, "description": "**Results per page.** Optional; defaults to `20`, accepts 1–200.\n\nValues above 200 are rejected with 400. Keep the same `page_size` on every page of one search so pages neither overlap nor skip results.", "name": "page_size", "in": "query" } ], "responses": { "200": { "description": "**Search the Motory Guide, the Saudi automotive business directory** (spare parts, workshops, car care, tyres, rentals, showrooms…), by name, address, city, make served, service, amenity, opening day, open now, provider kind and agent flag. Directory data covers Saudi Arabia only.\n\nEach row is a provider card as served: names in both languages, `link`, `city_id`, address, coordinates, `whatsapp_phone`, `description`, `is_agent`, `branch_count` and `media` images.\n\n- Rows are businesses (`is_company: false`) or companies (`is_company: true`). The two kinds have separate id spaces, so a row is identified by `is_company` plus `id`.\n- Companies carry their location on their branches, so their `city_id`, address and coordinates are null.\n\nNext calls:\n\n- a business `id` → `/directory-business-details?business_id=`\n- a company `id` → `/directory-company-details?company_id=` and `/directory-branches?company_id=` (`branch_count` locations)\n\nFilters and paging:\n\n- Filters combine with AND; a comma-separated list inside one filter matches any listed id.\n- `open_now` keeps the providers Motory lists as open right now (Saudi Arabia time). Motory does not count opening hours that end at or after midnight, so such providers are missing; `/directory-branches?open_now=true` counts them for a company's branches.\n- `open_now` already means today, so with `day` set to another weekday it returns 400.\n- A filter combination with too many ids or too long a text returns 400: send fewer ids in `city_id`, `make_id`, `service_id` or `amenity_id`, a shorter `address`, or more of the `name` (a short name matches many companies).\n- With `provider_type=company` and `sort=name_asc` or `name_desc`, more than 200 matching companies return 400 naming a narrower filter.\n- `pagination.total_items` counts every match; a `page` past `pagination.total_pages` returns an empty `items` list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MotorySuccessResponseSchema" }, "example": { "success": true, "data": { "items": [ { "id": 3221, "company_motory_id": null, "title": "Al Tawazon Al Thahabi Auto Spare Parts", "title_en": "Al Tawazon Al Thahabi Auto Spare Parts", "title_ar": "التوازن الذهبي لقطع غيار السيارات", "slug": "al-tawazon-al-thahabi-auto-spare-parts", "slug_en": "al-tawazon-al-thahabi-auto-spare-parts", "slug_ar": "التوازن-الذهبي-لقطع-غيار-السيارات", "link": "https://ksa.motory.com/en/guide/company/al-tawazon-al-thahabi-auto-spare-parts/", "city_id": 822, "address": "Al Faisaliyah Al Janubiyah, Tabuk 47911", "address_en": "Al Faisaliyah Al Janubiyah, Tabuk 47911", "address_ar": "الفيصلية الجنوبية، تبوك 47911", "latitude": "28.5474378", "longitude": "36.6230777", "whatsapp_phone": "0540305067", "description": "Auto Spare Parts", "is_agent": false, "branch_count": null, "is_company": false, "media": [ { "url": "https://motory-directory.s3.eu-central-1.amazonaws.com/live/business/3221/images/8a47a9e716d5b95046a1fa2124d7851e1790593343.jpg" } ] } ], "pagination": { "page": 1, "page_size": 20, "total_items": 2261, "total_pages": 114 } } } } } }, "400": { "description": "Bad request — a parameter is missing, malformed or out of range", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MotoryErrorResponseSchema" } } } }, "404": { "description": "Not found — the requested id or link does not exist", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MotoryErrorResponseSchema" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MotoryErrorResponseSchema" } } } }, "503": { "description": "Service busy — retry shortly", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MotoryErrorResponseSchema" } } } } } } }, "/directory-business-details": { "get": { "tags": [ "Directory" ], "operationId": "getDirectoryBusinessDetails", "description": "Read one directory business in full: contacts, address, images, services, amenities, weekly opening hours and the makes it serves. Takes a business_id from a /directory-search row with is_company false.", "parameters": [ { "schema": { "type": "integer", "description": "**Directory business id.** Required; for example `3221`.\n\nTake `id` from a `/directory-search` row with `is_company: false`. Company ids belong to `/directory-company-details`; an unknown id returns 404.", "minimum": 1, "example": 3221 }, "required": true, "description": "**Directory business id.** Required; for example `3221`.\n\nTake `id` from a `/directory-search` row with `is_company: false`. Company ids belong to `/directory-company-details`; an unknown id returns 404.", "name": "business_id", "in": "query" }, { "schema": { "type": "string", "description": "**Response language.** Optional; defaults to `en`.\n\n- `en` — English\n- `ar` — Arabic\n\nChanges labels, titles and descriptions only; ids and numeric values are the same in both languages.", "enum": [ "en", "ar" ], "default": "en" }, "required": false, "description": "**Response language.** Optional; defaults to `en`.\n\n- `en` — English\n- `ar` — Arabic\n\nChanges labels, titles and descriptions only; ids and numeric values are the same in both languages.", "name": "lang", "in": "query" } ], "responses": { "200": { "description": "**Read one business from the Motory Guide** (Saudi automotive business directory; Saudi Arabia only) in full.\n\nThe business as served:\n\n- names, description and address in both languages, coordinates, `whatsapp_phone`, `website_link`, `share_link`\n- `media` images, `city`, published `phones`, `services` and `amenities`\n- weekly opening hours: `workingDates[]` with `workingHours[]` time ranges and `is_24_hours`\n- the car `makes` it serves (`{id, title}`); `is_all_make: true` means every make\n- `service_provider_id` — the id of the provider profile that owns the business; it is not a business or company id, and no route takes it\n\nAn unknown `business_id` returns 404.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MotorySuccessResponseSchema" }, "example": { "success": true, "data": { "id": 3221, "service_provider_id": 2269, "title_ar": "التوازن الذهبي لقطع غيار السيارات", "title_en": "Al Tawazon Al Thahabi Auto Spare Parts", "slug_ar": "التوازن-الذهبي-لقطع-غيار-السيارات", "slug_en": "al-tawazon-al-thahabi-auto-spare-parts", "city_id": 822, "address_ar": "الفيصلية الجنوبية، تبوك 47911", "address_en": "Al Faisaliyah Al Janubiyah, Tabuk 47911", "latitude": "28.5474378", "longitude": "36.6230777", "whatsapp_phone": "0540305067", "website_link": "", "status": 1, "is_all_make": true, "sort_order": null, "created_at": "2026-09-28 17:02:26", "updated_at": "2026-09-28 17:02:26", "type": "service_company", "is_agent": false, "company_motory_id": null, "title": "Al Tawazon Al Thahabi Auto Spare Parts", "slug": "al-tawazon-al-thahabi-auto-spare-parts", "address": "Al Faisaliyah Al Janubiyah, Tabuk 47911", "description": "Auto Spare Parts", "other_service": null, "other_services_list": null, "show_report_flag": true, "holiday": null, "share_link": "https://ksa.motory.com/en/guide/company/al-tawazon-al-thahabi-auto-spare-parts", "media": [ { "url": "https://motory-directory.s3.eu-central-1.amazonaws.com/live/business/3221/images/8a47a9e716d5b95046a1fa2124d7851e1790593343.jpg" } ], "city": { "id": 822, "slug_en": "makkah-haraj", "name_ar": "مكة المكرمة", "name_en": "Makkah", "name": "Makkah" }, "phones": [ { "id": 3995, "phone": "0540305067", "title_ar": "966", "title_en": "966", "entity_type": "business", "entity_id": 3221, "status": 1, "bypass": 1, "created_at": "2026-09-28 17:02:27", "updated_at": "2026-09-28 17:02:27", "title": "966" } ], "services": [ { "id": 24, "title_ar": "قطع غيار سيارات", "title_en": "Car Spare Parts", "slug_ar": "قطع-غيار-سيارات", "slug_en": "car-spare-parts", "status": 1, "sort_order": 21, "created_at": "2024-05-15 12:21:08", "updated_at": "2024-05-16 09:11:36", "title": "Car Spare Parts", "slug": "car-spare-parts", "link": "https://ksa.motory.com/en/guide/car-spare-parts/" } ], "amenities": [ { "id": 14, "title_ar": "مواقف سيارات", "title_en": "Car Parking", "status": 1, "sort_order": 14, "created_at": "2024-04-29 13:34:21", "updated_at": "2024-04-29 13:34:22", "title": "Car Parking" } ], "workingDates": [ { "id": 66757, "day": "saturday", "entity_type": "business", "entity_id": 3221, "is_24_hours": false, "day_sort": 1, "created_at": "2026-09-28 17:02:27", "updated_at": "2026-09-28 17:02:27", "label": "Saturday", "workingHours": [ { "id": 95010, "working_date_id": 66757, "from": "08:00 AM", "to": "11:59 PM", "is_past_midnight": false, "created_at": "2026-09-28 17:02:27", "updated_at": "2026-09-28 17:02:27", "from_timestamp": 1791608400, "to_timestamp": 1791665940 } ] } ], "makes": [ { "id": 32, "title": "Audi" } ] } } } } }, "400": { "description": "Bad request — a parameter is missing, malformed or out of range", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MotoryErrorResponseSchema" } } } }, "404": { "description": "Not found — the requested id or link does not exist", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MotoryErrorResponseSchema" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MotoryErrorResponseSchema" } } } }, "503": { "description": "Service busy — retry shortly", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MotoryErrorResponseSchema" } } } } } } }, "/directory-company-details": { "get": { "tags": [ "Directory" ], "operationId": "getDirectoryCompanyDetails", "description": "Read one multi-branch directory company in full: contacts, images, services, amenities, opening hours, makes served and branch count. Takes a company_id from /directory-companies; list locations with /directory-branches.", "parameters": [ { "schema": { "type": "integer", "description": "**Directory company id.** Required; for example `2251`.\n\nTake `id` from `/directory-companies`, or from a `/directory-search` row with `is_company: true`. Business ids belong to `/directory-business-details`; an unknown id returns 404.", "minimum": 1, "example": 2251 }, "required": true, "description": "**Directory company id.** Required; for example `2251`.\n\nTake `id` from `/directory-companies`, or from a `/directory-search` row with `is_company: true`. Business ids belong to `/directory-business-details`; an unknown id returns 404.", "name": "company_id", "in": "query" }, { "schema": { "type": "string", "description": "**Response language.** Optional; defaults to `en`.\n\n- `en` — English\n- `ar` — Arabic\n\nChanges labels, titles and descriptions only; ids and numeric values are the same in both languages.", "enum": [ "en", "ar" ], "default": "en" }, "required": false, "description": "**Response language.** Optional; defaults to `en`.\n\n- `en` — English\n- `ar` — Arabic\n\nChanges labels, titles and descriptions only; ids and numeric values are the same in both languages.", "name": "lang", "in": "query" } ], "responses": { "200": { "description": "**Read one multi-branch company from the Motory Guide** (Saudi automotive business directory; Saudi Arabia only) in full.\n\nThe company as served:\n\n- names and description in both languages, `whatsapp`, `website_link`, `other_services_list`, `share_link`, `branch_count`\n- `media` images, published `phones`, `services` and `amenities`\n- weekly opening hours: `workingDates[]` with `workingHours[]` time ranges\n- the car `makes` it serves (`{id, title}`); `is_all_make: true` means every make\n\nA company has no single address: list its locations, with each branch's phones and hours, with `/directory-branches?company_id=`. An unknown `company_id` returns 404.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MotorySuccessResponseSchema" }, "example": { "success": true, "data": { "id": 2251, "company_motory_id": null, "title_ar": "نانو سيراميك", "title_en": "Nano Ceramic", "slug_ar": "نانو-سيراميك", "slug_en": "nano-ceramic", "status": 1, "is_all_make": false, "sort_order": null, "whatsapp": "0535888273", "website_link": "", "country_id": null, "created_at": "2025-10-02 22:18:57", "updated_at": "2026-01-27 18:42:03", "is_group_business": 1, "type": "service_company", "is_agent": true, "company_id": null, "title": "Nano Ceramic", "slug": "nano-ceramic", "link": "https://ksa.motory.com/en/guide/company/nano-ceramic/", "description": "Car care (thermal insulation, PPF paint protection, exterior and interior polishing, exterior and interior nano ceramic)", "other_service": "

All cars except trucks

", "other_services_list": [ "All cars except trucks" ], "branch_count": 10, "show_report_flag": true, "share_link": "https://ksa.motory.com/en/guide/company/nano-ceramic", "media": [ { "url": "https://motory-directory.s3.eu-central-1.amazonaws.com/live/service_provider/2251/images/22054b5f6213b836e8ca97f8ee57421a1759421812.jpg" } ] } ], "pagination": { "page": 1, "page_size": 20, "total_items": 85, "total_pages": 5 } } } } } }, "400": { "description": "Bad request — a parameter is missing, malformed or out of range", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MotoryErrorResponseSchema" } } } }, "404": { "description": "Not found — the requested id or link does not exist", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MotoryErrorResponseSchema" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MotoryErrorResponseSchema" } } } }, "503": { "description": "Service busy — retry shortly", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MotoryErrorResponseSchema" } } } } } } }, "/directory-branches": { "get": { "tags": [ "Directory" ], "operationId": "listDirectoryCompanyBranches", "description": "List the branches of one directory company with address, coordinates, phones, weekly opening hours and each branch's services, amenities and makes, optionally by city, service, amenity, make, address, opening day or open now. Takes a company_id from /directory-companies.", "parameters": [ { "schema": { "type": "integer", "description": "**Directory company id.** Required; for example `2251`.\n\nTake `id` from `/directory-companies`, or from a `/directory-search` row with `is_company: true`. A business id or an unknown id returns 404.", "minimum": 1, "example": 2251 }, "required": true, "description": "**Directory company id.** Required; for example `2251`.\n\nTake `id` from `/directory-companies`, or from a `/directory-search` row with `is_company: true`. A business id or an unknown id returns 404.", "name": "company_id", "in": "query" }, { "schema": { "type": "string", "description": "**City filter.** Optional; one or more city ids, comma-separated (for example `810,821`); any listed city matches.\n\nTake ids from `/directory-cities`." }, "required": false, "description": "**City filter.** Optional; one or more city ids, comma-separated (for example `810,821`); any listed city matches.\n\nTake ids from `/directory-cities`.", "name": "city_id", "in": "query" }, { "schema": { "type": "string", "description": "**Service offered at the branch** (spare parts, car wash, tyres, inspection…). Optional; one or more service ids, comma-separated; any listed service matches.\n\nTake ids from `/directory-services`. Branches of one company can offer different services." }, "required": false, "description": "**Service offered at the branch** (spare parts, car wash, tyres, inspection…). Optional; one or more service ids, comma-separated; any listed service matches.\n\nTake ids from `/directory-services`. Branches of one company can offer different services.", "name": "service_id", "in": "query" }, { "schema": { "type": "string", "description": "**Amenity at the branch** (parking, waiting area, card payment…). Optional; one or more amenity ids, comma-separated; any listed amenity matches.\n\nTake ids from `/directory-amenities`." }, "required": false, "description": "**Amenity at the branch** (parking, waiting area, card payment…). Optional; one or more amenity ids, comma-separated; any listed amenity matches.\n\nTake ids from `/directory-amenities`.", "name": "amenity_id", "in": "query" }, { "schema": { "type": "string", "description": "**Car make served at the branch.** Optional; one or more make ids, comma-separated; any listed make matches.\n\nTake ids from `/directory-makes`. Branches that serve every make (`is_all_make: true`) match any make." }, "required": false, "description": "**Car make served at the branch.** Optional; one or more make ids, comma-separated; any listed make matches.\n\nTake ids from `/directory-makes`. Branches that serve every make (`is_all_make: true`) match any make.", "name": "make_id", "in": "query" }, { "schema": { "type": "string", "description": "**Address text.** Optional; English or Arabic, case-insensitive substring of the branch address (for example a district or street name).", "maxLength": 100 }, "required": false, "description": "**Address text.** Optional; English or Arabic, case-insensitive substring of the branch address (for example a district or street name).", "name": "address", "in": "query" }, { "schema": { "type": "string", "description": "**Open on this weekday.** Optional; keeps branches with opening hours on that day.\n\n- `sunday` — Sunday\n- `monday` — Monday\n- `tuesday` — Tuesday\n- `wednesday` — Wednesday\n- `thursday` — Thursday\n- `friday` — Friday\n- `saturday` — Saturday", "enum": [ "sunday", "monday", "tuesday", "wednesday", "thursday", "friday", "saturday" ] }, "required": false, "description": "**Open on this weekday.** Optional; keeps branches with opening hours on that day.\n\n- `sunday` — Sunday\n- `monday` — Monday\n- `tuesday` — Tuesday\n- `wednesday` — Wednesday\n- `thursday` — Thursday\n- `friday` — Friday\n- `saturday` — Saturday", "name": "day", "in": "query" }, { "schema": { "type": "boolean", "description": "**Only branches open right now** (Saudi Arabia time). Optional.\n\n- `true` — keep only branches whose published opening hours cover the current time\n- omitted — branches whatever their opening state\n\n`false` is rejected with 400: there is no \"closed now\" filter. `open_now` already means today, so it combines with `day` only when `day` is today's weekday in Saudi Arabia; any other `day` returns 400.\n\nHours that run past midnight (for example `07:00 AM–01:00 AM`) count as open until their closing time on the next day.", "example": "" }, "required": false, "description": "**Only branches open right now** (Saudi Arabia time). Optional.\n\n- `true` — keep only branches whose published opening hours cover the current time\n- omitted — branches whatever their opening state\n\n`false` is rejected with 400: there is no \"closed now\" filter. `open_now` already means today, so it combines with `day` only when `day` is today's weekday in Saudi Arabia; any other `day` returns 400.\n\nHours that run past midnight (for example `07:00 AM–01:00 AM`) count as open until their closing time on the next day.", "name": "open_now", "in": "query" }, { "schema": { "type": "string", "description": "**Response language.** Optional; defaults to `en`.\n\n- `en` — English\n- `ar` — Arabic\n\nChanges labels, titles and descriptions only; ids and numeric values are the same in both languages.", "enum": [ "en", "ar" ], "default": "en" }, "required": false, "description": "**Response language.** Optional; defaults to `en`.\n\n- `en` — English\n- `ar` — Arabic\n\nChanges labels, titles and descriptions only; ids and numeric values are the same in both languages.", "name": "lang", "in": "query" }, { "schema": { "type": "integer", "description": "**Page number, starting at 1.** Optional; defaults to `1`.\n\nKeep `page_size` fixed while paging and stop at `pagination.total_pages`. A `page` beyond the last page returns an empty `items` list.", "minimum": 1, "maximum": 10000, "default": 1 }, "required": false, "description": "**Page number, starting at 1.** Optional; defaults to `1`.\n\nKeep `page_size` fixed while paging and stop at `pagination.total_pages`. A `page` beyond the last page returns an empty `items` list.", "name": "page", "in": "query" }, { "schema": { "type": "integer", "description": "**Results per page.** Optional; defaults to `20`, accepts 1–200.\n\nValues above 200 are rejected with 400. Keep the same `page_size` on every page of one search so pages neither overlap nor skip results.", "minimum": 1, "maximum": 200, "default": 20 }, "required": false, "description": "**Results per page.** Optional; defaults to `20`, accepts 1–200.\n\nValues above 200 are rejected with 400. Keep the same `page_size` on every page of one search so pages neither overlap nor skip results.", "name": "page_size", "in": "query" } ], "responses": { "200": { "description": "**List the locations of one Motory Guide company** (Saudi automotive business directory; Saudi Arabia only), optionally narrowed by city, service, amenity, make served, address, opening day or open now.\n\nEach row is a branch as served:\n\n- `city_id`, address in both languages, coordinates, `media` images and the branch's published `phones`\n- weekly opening hours: `workingDates[]` with `workingHours[]` time ranges and `is_24_hours`\n- the branch's own `services`, `amenities` and car `makes` (`{id, title}`; `is_all_make: true` means every make). Branches of one company can differ in these; `/directory-company-details` shows the company-wide lists.\n- branch names and descriptions, usually null: a branch goes by its company's name (`/directory-company-details`)\n- `service_provider_id` — the `company_id`\n\nFilters and paging:\n\n- Filters combine with AND; a comma-separated list inside one filter matches any listed id.\n- `open_now` is judged from each branch's published opening hours (Saudi Arabia time); hours that run past midnight count as open until their closing time on the next day.\n- Too many branches matching `make_id`, `open_now` or several `service_id` or `amenity_id` ids return 400: add `city_id`, or send fewer ids.\n- `pagination.total_items` counts every match; a `page` past `pagination.total_pages` returns an empty `items` list.\n- A real company with no branch matching the filters returns an empty `items` list; a `company_id` that is not a directory company returns 404.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MotorySuccessResponseSchema" }, "example": { "success": true, "data": { "items": [ { "id": 3201, "service_provider_id": 2251, "title_ar": null, "title_en": null, "slug_ar": null, "slug_en": null, "description_ar": null, "description_en": null, "city_id": 810, "address_ar": "شارع / وادي الساحل حي / القادسية", "address_en": "Street / Wadi Al-Sahel District / Al-Qadisiyah", "latitude": "24.8184899", "longitude": "46.8176064", "whatsapp_phone": null, "website_link": null, "status": 1, "is_all_make": false, "sort_order": null, "created_at": "2025-10-08 14:21:29", "updated_at": "2025-10-08 19:20:04", "type": null, "is_agent": false, "company_motory_id": null, "title": null, "address": "Street / Wadi Al-Sahel District / Al-Qadisiyah", "other_service": null, "other_services_list": null, "show_report_flag": true, "holiday": null, "media": [ { "url": "https://motory-directory.s3.eu-central-1.amazonaws.com/live/business/3201/images/936a329412e3fb95f04851cc66a279771759911776.jpg" } ], "phones": [ { "id": 3972, "phone": "0535888273", "title_ar": "966", "title_en": "966", "entity_type": "branch", "entity_id": 3201, "status": 1, "bypass": 1, "created_at": "2025-10-08 14:21:29", "updated_at": "2025-10-08 14:21:29", "title": "966" } ], "workingDates": [ { "id": 66328, "day": "saturday", "entity_type": "branch", "entity_id": 3201, "is_24_hours": false, "day_sort": 1, "created_at": "2025-10-08 19:20:04", "updated_at": "2025-10-08 19:20:04", "label": "Saturday", "workingHours": [ { "id": 94482, "working_date_id": 66328, "from": "09:00 AM", "to": "01:00 PM", "is_past_midnight": false, "created_at": "2025-10-08 19:20:04", "updated_at": "2025-10-08 19:20:04", "from_timestamp": 1791612000, "to_timestamp": 1791626400 } ] } ], "services": [ { "id": 15, "title_ar": "خدمات العناية بالسيارة", "title_en": "Auto Care", "slug_ar": "خدمات-العناية-بالسيارة", "slug_en": "auto-care", "status": 1, "sort_order": 12, "created_at": "2024-04-29 11:44:21", "updated_at": "2024-05-16 09:11:36", "title": "Auto Care", "slug": "auto-care", "link": "https://ksa.motory.com/en/guide/auto-care/" } ], "amenities": [ { "id": 1, "title_ar": "منطقة انتظار عامة", "title_en": "Waiting Area", "status": 1, "sort_order": 1, "created_at": "2024-04-29 13:26:46", "updated_at": "2024-04-29 13:26:46", "title": "Waiting Area" } ], "makes": [ { "id": 32, "title": "Audi" } ] }, { "id": 3193, "service_provider_id": 2251, "title_ar": null, "title_en": null, "slug_ar": null, "slug_en": null, "description_ar": null, "description_en": null, "city_id": 812, "address_ar": "المركز الرئيسي شارع الملك فهد حي / قرطبة", "address_en": "Main Center, King Fahd Street, Qurtuba District", "latitude": "26.352038", "longitude": "50.1912928", "whatsapp_phone": null, "website_link": null, "status": 1, "is_all_make": false, "sort_order": null, "created_at": "2025-10-02 22:43:27", "updated_at": "2025-10-08 19:10:59", "type": null, "is_agent": false, "company_motory_id": null, "title": null, "address": "Main Center, King Fahd Street, Qurtuba District", "other_service": "

All cars except trucks

", "other_services_list": [ "All cars except trucks" ], "show_report_flag": true, "holiday": null, "media": [ { "url": "https://motory-directory.s3.eu-central-1.amazonaws.com/live/business/3193/images/936a329412e3fb95f04851cc66a279771759911917.jpg" } ], "phones": [ { "id": 3964, "phone": "0535888273", "title_ar": "966", "title_en": "966", "entity_type": "branch", "entity_id": 3193, "status": 1, "bypass": 1, "created_at": "2025-10-02 22:43:27", "updated_at": "2025-10-02 22:43:27", "title": "966" } ], "workingDates": [ { "id": 66304, "day": "saturday", "entity_type": "branch", "entity_id": 3193, "is_24_hours": false, "day_sort": 1, "created_at": "2025-10-08 19:10:59", "updated_at": "2025-10-08 19:10:59", "label": "Saturday", "workingHours": [ { "id": 94434, "working_date_id": 66304, "from": "09:00 AM", "to": "01:00 PM", "is_past_midnight": false, "created_at": "2025-10-08 19:10:59", "updated_at": "2025-10-08 19:10:59", "from_timestamp": 1791612000, "to_timestamp": 1791626400 } ] } ], "services": [ { "id": 15, "title_ar": "خدمات العناية بالسيارة", "title_en": "Auto Care", "slug_ar": "خدمات-العناية-بالسيارة", "slug_en": "auto-care", "status": 1, "sort_order": 12, "created_at": "2024-04-29 11:44:21", "updated_at": "2024-05-16 09:11:36", "title": "Auto Care", "slug": "auto-care", "link": "https://ksa.motory.com/en/guide/auto-care/" } ], "amenities": [ { "id": 1, "title_ar": "منطقة انتظار عامة", "title_en": "Waiting Area", "status": 1, "sort_order": 1, "created_at": "2024-04-29 13:26:46", "updated_at": "2024-04-29 13:26:46", "title": "Waiting Area" } ], "makes": [ { "id": 32, "title": "Audi" } ] } ], "pagination": { "page": 1, "page_size": 20, "total_items": 10, "total_pages": 1 } } } } } }, "400": { "description": "Bad request — a parameter is missing, malformed or out of range", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MotoryErrorResponseSchema" } } } }, "404": { "description": "Not found — the requested id or link does not exist", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MotoryErrorResponseSchema" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MotoryErrorResponseSchema" } } } }, "503": { "description": "Service busy — retry shortly", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MotoryErrorResponseSchema" } } } } } } }, "/directory-services": { "get": { "tags": [ "Directory" ], "operationId": "listDirectoryServices", "description": "List every service category of the Saudi automotive directory (spare parts, car wash, tyres, inspection, rentals, showrooms) with names in both languages. Use an id as service_id on /directory-search and /directory-branches.", "parameters": [ { "schema": { "type": "string", "description": "**Response language.** Optional; defaults to `en`.\n\n- `en` — English\n- `ar` — Arabic\n\nChanges labels, titles and descriptions only; ids and numeric values are the same in both languages.", "enum": [ "en", "ar" ], "default": "en" }, "required": false, "description": "**Response language.** Optional; defaults to `en`.\n\n- `en` — English\n- `ar` — Arabic\n\nChanges labels, titles and descriptions only; ids and numeric values are the same in both languages.", "name": "lang", "in": "query" } ], "responses": { "200": { "description": "**Every service category of the Motory Guide** (Saudi automotive business directory; Saudi Arabia only) as `{items}`: spare parts, car wash, tyres, inspection, rentals, showrooms and more.\n\n- Each item has names and slugs in both languages and the public `link`.\n- Use an `id` as `service_id` on `/directory-search` and `/directory-branches`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MotorySuccessResponseSchema" }, "example": { "success": true, "data": { "items": [ { "id": 24, "title_ar": "قطع غيار سيارات", "title_en": "Car Spare Parts", "slug_ar": "قطع-غيار-سيارات", "slug_en": "car-spare-parts", "status": 1, "sort_order": 21, "created_at": "2024-05-15 12:21:08", "updated_at": "2024-05-16 09:11:36", "title": "Car Spare Parts", "slug": "car-spare-parts", "link": "https://ksa.motory.com/en/guide/car-spare-parts/" } ] } } } } }, "400": { "description": "Bad request — a parameter is missing, malformed or out of range", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MotoryErrorResponseSchema" } } } }, "404": { "description": "Not found — the requested id or link does not exist", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MotoryErrorResponseSchema" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MotoryErrorResponseSchema" } } } }, "503": { "description": "Service busy — retry shortly", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MotoryErrorResponseSchema" } } } } } } }, "/directory-amenities": { "get": { "tags": [ "Directory" ], "operationId": "listDirectoryAmenities", "description": "List every amenity a directory provider can offer (waiting area, parking, Wi-Fi, payment methods) with names in both languages. Takes no id; use an id as amenity_id on /directory-search and /directory-branches.", "parameters": [ { "schema": { "type": "string", "description": "**Response language.** Optional; defaults to `en`.\n\n- `en` — English\n- `ar` — Arabic\n\nChanges labels, titles and descriptions only; ids and numeric values are the same in both languages.", "enum": [ "en", "ar" ], "default": "en" }, "required": false, "description": "**Response language.** Optional; defaults to `en`.\n\n- `en` — English\n- `ar` — Arabic\n\nChanges labels, titles and descriptions only; ids and numeric values are the same in both languages.", "name": "lang", "in": "query" } ], "responses": { "200": { "description": "**Every amenity a Motory Guide provider can list** (Saudi automotive business directory; Saudi Arabia only) as `{items}`: waiting areas, parking, Wi-Fi, payment methods, loyalty-point redemption and more.\n\n- Each item has names in both languages.\n- Use an `id` as `amenity_id` on `/directory-search` and `/directory-branches`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MotorySuccessResponseSchema" }, "example": { "success": true, "data": { "items": [ { "id": 24, "title_ar": "ادفع باستخدام تابي", "title_en": "Pay With Tabby", "status": 1, "sort_order": null, "created_at": "2025-01-12 14:48:31", "updated_at": "2025-01-12 14:48:31", "title": "Pay With Tabby" } ] } } } } }, "400": { "description": "Bad request — a parameter is missing, malformed or out of range", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MotoryErrorResponseSchema" } } } }, "404": { "description": "Not found — the requested id or link does not exist", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MotoryErrorResponseSchema" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MotoryErrorResponseSchema" } } } }, "503": { "description": "Service busy — retry shortly", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MotoryErrorResponseSchema" } } } } } } }, "/directory-cities": { "get": { "tags": [ "Directory" ], "operationId": "listDirectoryCities", "description": "List the Saudi cities of the business directory with names and slugs in both languages. Takes no id; use an id as city_id on /directory-search and /directory-branches.", "parameters": [ { "schema": { "type": "string", "description": "**Response language.** Optional; defaults to `en`.\n\n- `en` — English\n- `ar` — Arabic\n\nChanges labels, titles and descriptions only; ids and numeric values are the same in both languages.", "enum": [ "en", "ar" ], "default": "en" }, "required": false, "description": "**Response language.** Optional; defaults to `en`.\n\n- `en` — English\n- `ar` — Arabic\n\nChanges labels, titles and descriptions only; ids and numeric values are the same in both languages.", "name": "lang", "in": "query" } ], "responses": { "200": { "description": "**Every Saudi city of the Motory Guide** (Saudi automotive business directory) as `{items}`, with names and slugs in both languages.\n\n- Use an `id` as `city_id` on `/directory-search` and `/directory-branches`.\n- The ids are the Saudi marketplace city ids, so the same id also filters Saudi (`country=sa`) car searches.\n- Not every city has listed providers.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MotorySuccessResponseSchema" }, "example": { "success": true, "data": { "items": [ { "id": 805, "slug_ar": "الخرج", "slug_en": "al-kharj", "title_ar": "الخرج", "title_en": "Al Kharj", "name": "Al Kharj", "slug": "al-kharj-haraj" } ] } } } } }, "400": { "description": "Bad request — a parameter is missing, malformed or out of range", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MotoryErrorResponseSchema" } } } }, "404": { "description": "Not found — the requested id or link does not exist", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MotoryErrorResponseSchema" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MotoryErrorResponseSchema" } } } }, "503": { "description": "Service busy — retry shortly", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MotoryErrorResponseSchema" } } } } } } }, "/directory-makes": { "get": { "tags": [ "Directory" ], "operationId": "listDirectoryMakes", "description": "List the car makes a directory provider can serve, with names in both languages, logo and link; it also covers trucks, motorcycles and heavy equipment. Use an id as make_id on /directory-search and /directory-branches.", "parameters": [ { "schema": { "type": "string", "description": "**Response language.** Optional; defaults to `en`.\n\n- `en` — English\n- `ar` — Arabic\n\nChanges labels, titles and descriptions only; ids and numeric values are the same in both languages.", "enum": [ "en", "ar" ], "default": "en" }, "required": false, "description": "**Response language.** Optional; defaults to `en`.\n\n- `en` — English\n- `ar` — Arabic\n\nChanges labels, titles and descriptions only; ids and numeric values are the same in both languages.", "name": "lang", "in": "query" } ], "responses": { "200": { "description": "**Every car make a Motory Guide provider can serve** (Saudi automotive business directory; Saudi Arabia only) as `{items}`, with names in both languages, `logo` and the public `link`.\n\n- Use an `id` as `make_id` on `/directory-search` and `/directory-branches`.\n- The ids are the Saudi marketplace make ids, but this list is wider than the car-listing makes: it also covers trucks, motorcycles and heavy-equipment brands.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MotorySuccessResponseSchema" }, "example": { "success": true, "data": { "items": [ { "id": 90, "title_ar": "تويوتا", "title_en": "Toyota", "slug_ar": "تويوتا", "slug_en": "toyota", "title": "Toyota", "logo": "https://s3.eu-central-1.amazonaws.com/v3-common.motory.com/taxonomy/60x60/l-1669878465.8496-638852c1cf6f3.webp", "slug": "toyota", "link": "https://ksa.motory.com/en/guide-make/toyota/" } ] } } } } }, "400": { "description": "Bad request — a parameter is missing, malformed or out of range", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MotoryErrorResponseSchema" } } } }, "404": { "description": "Not found — the requested id or link does not exist", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MotoryErrorResponseSchema" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MotoryErrorResponseSchema" } } } }, "503": { "description": "Service busy — retry shortly", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MotoryErrorResponseSchema" } } } } } } }, "/news-categories": { "get": { "tags": [ "News" ], "operationId": "listNewsCategories", "description": "List the news categories of a market and language (Car News, Local News, Car Reports, Car Advice). Takes only country and lang; pass a category id as category_id to /category-news, or as a filter on /news-search, /author-news and /tag-news.", "parameters": [ { "schema": { "type": "string", "description": "**Market to read.** Optional; defaults to `sa`.\n\n- `sa` — Saudi Arabia (prices in SAR)\n- `jo` — Jordan (prices in JOD)\n\nEach market has its own inventory and its own ids (makes, models, cities, body types, dealers, vehicles). Send only ids from a call made with the same `country`. An id from the other market is answered as an unknown id:\n\n- **404** — a lookup by id: every details route, `/models`, `/finance-providers`, and `category_id` on `/category-news` and `/videos`.\n- **400 naming the param** — `make_id`, `model_id` and `finance_provider_id` on `/new-cars` and `/new-car-filters`; `make_id` and `city_id` on `/dealers`; `make_id` and `company_id` on `/offers`; `make_id`, `author_id` and `category_id` as filters of the news lists, and `make_id` on `/videos` (on `/tag-news`, an unknown `author_id` with a tag that is not a make returns an empty list when the tag has articles in the requested `lang`, and 404 otherwise).\n- **Empty result** — every other id filter, for example `body_type_id`, `fuel_type_id`, `transmission_id` or `origin_id` on `/new-cars`, every `/used-cars` and `/used-car-filters` filter, and `dealer_id` on `/dealers`.", "enum": [ "sa", "jo" ], "default": "sa" }, "required": false, "description": "**Market to read.** Optional; defaults to `sa`.\n\n- `sa` — Saudi Arabia (prices in SAR)\n- `jo` — Jordan (prices in JOD)\n\nEach market has its own inventory and its own ids (makes, models, cities, body types, dealers, vehicles). Send only ids from a call made with the same `country`. An id from the other market is answered as an unknown id:\n\n- **404** — a lookup by id: every details route, `/models`, `/finance-providers`, and `category_id` on `/category-news` and `/videos`.\n- **400 naming the param** — `make_id`, `model_id` and `finance_provider_id` on `/new-cars` and `/new-car-filters`; `make_id` and `city_id` on `/dealers`; `make_id` and `company_id` on `/offers`; `make_id`, `author_id` and `category_id` as filters of the news lists, and `make_id` on `/videos` (on `/tag-news`, an unknown `author_id` with a tag that is not a make returns an empty list when the tag has articles in the requested `lang`, and 404 otherwise).\n- **Empty result** — every other id filter, for example `body_type_id`, `fuel_type_id`, `transmission_id` or `origin_id` on `/new-cars`, every `/used-cars` and `/used-car-filters` filter, and `dealer_id` on `/dealers`.", "name": "country", "in": "query" }, { "schema": { "type": "string", "description": "**Language of the news — and which articles you get.** Optional; defaults to `en`.\n\n- `en` — English\n- `ar` — Arabic\n\nNews is written separately in each language:\n\n- Each language has its own set of articles, and some articles and categories exist in one language only.\n- Ids are the same in both languages, but a list can hold different articles in each.\n- An article published in one language only returns 404 in the other; the message names the `lang` to use.", "enum": [ "en", "ar" ], "default": "en" }, "required": false, "description": "**Language of the news — and which articles you get.** Optional; defaults to `en`.\n\n- `en` — English\n- `ar` — Arabic\n\nNews is written separately in each language:\n\n- Each language has its own set of articles, and some articles and categories exist in one language only.\n- Ids are the same in both languages, but a list can hold different articles in each.\n- An article published in one language only returns 404 in the other; the message names the `lang` to use.", "name": "lang", "in": "query" } ], "responses": { "200": { "description": "**The news categories of one market and language**, as `items: [{id, name}]` (Car News, Local News, Car Reports, Car Advice, Auto Sports News…).\n\n- Pass an `id` as `category_id` to `/category-news`, or as a filter on `/news-search`, `/author-news` and `/tag-news`.\n- The `-1` entry (\"Home\") is the \"All\" entry: it stands for every category and is not a category id. Omit `category_id` on the filter routes to get all categories; `/category-news` needs a real category id and rejects `-1` with 400.\n- Category ids differ between markets.\n- The list can differ between languages: some categories have articles in one language only.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MotorySuccessResponseSchema" }, "example": { "success": true, "data": { "items": [ { "id": -1, "name": "Home" } ] } } } } }, "400": { "description": "Bad request — a parameter is missing, malformed or out of range", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MotoryErrorResponseSchema" } } } }, "404": { "description": "Not found — the requested id or link does not exist", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MotoryErrorResponseSchema" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MotoryErrorResponseSchema" } } } }, "503": { "description": "Service busy — retry shortly", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MotoryErrorResponseSchema" } } } } } } }, "/category-news": { "get": { "tags": [ "News" ], "operationId": "getNewsByCategory", "description": "List the news articles of one category, newest, oldest or most-read first, optionally narrowed to one author, one make or a title text, as article cards with title, date, author, image and excerpt. Takes a category_id from /news-categories; open a row's id in /news-details.", "parameters": [ { "schema": { "type": "integer", "description": "**News category id.** Required; for example `626` (Car News in `sa`).\n\nTake `id` from `/news-categories` called with the same `country`. An id that is not a news category of the selected market (in either language) returns 404; a category with no articles in the requested language returns an empty list.", "minimum": 1, "example": 626 }, "required": true, "description": "**News category id.** Required; for example `626` (Car News in `sa`).\n\nTake `id` from `/news-categories` called with the same `country`. An id that is not a news category of the selected market (in either language) returns 404; a category with no articles in the requested language returns an empty list.", "name": "category_id", "in": "query" }, { "schema": { "type": "integer", "description": "**Only articles by this author.** Optional; one author id.\n\nTake `author.id` from any article row fetched with the same `country`. An id that is not a news author of the selected market is rejected with 400.", "minimum": 1 }, "required": false, "description": "**Only articles by this author.** Optional; one author id.\n\nTake `author.id` from any article row fetched with the same `country`. An id that is not a news author of the selected market is rejected with 400.", "name": "author_id", "in": "query" }, { "schema": { "type": "integer", "description": "**Only articles about this make.** Optional; one make id.\n\nTake ids from `/makes` called with the same `country` (`condition=used` or `new`). A make without matching news returns an empty list; an id that is in neither `/makes` list of the selected market is rejected with 400.", "minimum": 1 }, "required": false, "description": "**Only articles about this make.** Optional; one make id.\n\nTake ids from `/makes` called with the same `country` (`condition=used` or `new`). A make without matching news returns an empty list; an id that is in neither `/makes` list of the selected market is rejected with 400.", "name": "make_id", "in": "query" }, { "schema": { "type": "string", "description": "**Only articles whose title contains this text**, case-insensitive. Optional; for example `toyota`.\n\nWrite Arabic text with `lang=ar` and English text with `lang=en`. No match returns an empty list.", "maxLength": 100 }, "required": false, "description": "**Only articles whose title contains this text**, case-insensitive. Optional; for example `toyota`.\n\nWrite Arabic text with `lang=ar` and English text with `lang=en`. No match returns an empty list.", "name": "keyword", "in": "query" }, { "schema": { "type": "string", "description": "**Article order.** Optional; defaults to `newest`.\n\n- `newest` — most recently published first\n- `oldest` — earliest published first\n- `most_read` — most-read articles first\n\nEvery filter applies under every order. `most_read` is the order of `/author-news` with `order_by=most_read`: an author's articles narrowed here with `author_id` come in the same order there, except that neighbouring articles can swap places.", "enum": [ "newest", "oldest", "most_read" ], "default": "newest" }, "required": false, "description": "**Article order.** Optional; defaults to `newest`.\n\n- `newest` — most recently published first\n- `oldest` — earliest published first\n- `most_read` — most-read articles first\n\nEvery filter applies under every order. `most_read` is the order of `/author-news` with `order_by=most_read`: an author's articles narrowed here with `author_id` come in the same order there, except that neighbouring articles can swap places.", "name": "sort", "in": "query" }, { "schema": { "type": "string", "description": "**Market to read.** Optional; defaults to `sa`.\n\n- `sa` — Saudi Arabia (prices in SAR)\n- `jo` — Jordan (prices in JOD)\n\nEach market has its own inventory and its own ids (makes, models, cities, body types, dealers, vehicles). Send only ids from a call made with the same `country`. An id from the other market is answered as an unknown id:\n\n- **404** — a lookup by id: every details route, `/models`, `/finance-providers`, and `category_id` on `/category-news` and `/videos`.\n- **400 naming the param** — `make_id`, `model_id` and `finance_provider_id` on `/new-cars` and `/new-car-filters`; `make_id` and `city_id` on `/dealers`; `make_id` and `company_id` on `/offers`; `make_id`, `author_id` and `category_id` as filters of the news lists, and `make_id` on `/videos` (on `/tag-news`, an unknown `author_id` with a tag that is not a make returns an empty list when the tag has articles in the requested `lang`, and 404 otherwise).\n- **Empty result** — every other id filter, for example `body_type_id`, `fuel_type_id`, `transmission_id` or `origin_id` on `/new-cars`, every `/used-cars` and `/used-car-filters` filter, and `dealer_id` on `/dealers`.", "enum": [ "sa", "jo" ], "default": "sa" }, "required": false, "description": "**Market to read.** Optional; defaults to `sa`.\n\n- `sa` — Saudi Arabia (prices in SAR)\n- `jo` — Jordan (prices in JOD)\n\nEach market has its own inventory and its own ids (makes, models, cities, body types, dealers, vehicles). Send only ids from a call made with the same `country`. An id from the other market is answered as an unknown id:\n\n- **404** — a lookup by id: every details route, `/models`, `/finance-providers`, and `category_id` on `/category-news` and `/videos`.\n- **400 naming the param** — `make_id`, `model_id` and `finance_provider_id` on `/new-cars` and `/new-car-filters`; `make_id` and `city_id` on `/dealers`; `make_id` and `company_id` on `/offers`; `make_id`, `author_id` and `category_id` as filters of the news lists, and `make_id` on `/videos` (on `/tag-news`, an unknown `author_id` with a tag that is not a make returns an empty list when the tag has articles in the requested `lang`, and 404 otherwise).\n- **Empty result** — every other id filter, for example `body_type_id`, `fuel_type_id`, `transmission_id` or `origin_id` on `/new-cars`, every `/used-cars` and `/used-car-filters` filter, and `dealer_id` on `/dealers`.", "name": "country", "in": "query" }, { "schema": { "type": "string", "description": "**Language of the news — and which articles you get.** Optional; defaults to `en`.\n\n- `en` — English\n- `ar` — Arabic\n\nNews is written separately in each language:\n\n- Each language has its own set of articles, and some articles and categories exist in one language only.\n- Ids are the same in both languages, but a list can hold different articles in each.\n- An article published in one language only returns 404 in the other; the message names the `lang` to use.", "enum": [ "en", "ar" ], "default": "en" }, "required": false, "description": "**Language of the news — and which articles you get.** Optional; defaults to `en`.\n\n- `en` — English\n- `ar` — Arabic\n\nNews is written separately in each language:\n\n- Each language has its own set of articles, and some articles and categories exist in one language only.\n- Ids are the same in both languages, but a list can hold different articles in each.\n- An article published in one language only returns 404 in the other; the message names the `lang` to use.", "name": "lang", "in": "query" }, { "schema": { "type": "integer", "description": "**Page number, starting at 1.** Optional; defaults to `1`.\n\nKeep `page_size` fixed while paging and stop at `pagination.total_pages`. A `page` beyond the last page returns an empty `items` list.", "minimum": 1, "maximum": 10000, "default": 1 }, "required": false, "description": "**Page number, starting at 1.** Optional; defaults to `1`.\n\nKeep `page_size` fixed while paging and stop at `pagination.total_pages`. A `page` beyond the last page returns an empty `items` list.", "name": "page", "in": "query" }, { "schema": { "type": "integer", "description": "**Results per page.** Optional; defaults to `20`, accepts 1–50.\n\nValues above 50 are rejected with 400. Keep the same `page_size` on every page of one search so pages neither overlap nor skip results.", "minimum": 1, "maximum": 50, "default": 20 }, "required": false, "description": "**Results per page.** Optional; defaults to `20`, accepts 1–50.\n\nValues above 50 are rejected with 400. Keep the same `page_size` on every page of one search so pages neither overlap nor skip results.", "name": "page_size", "in": "query" } ], "responses": { "200": { "description": "**The news articles of one category**, newest first by default (or oldest or most-read first), optionally narrowed to one author, one make or a title text. Filters combine: every one must match.\n\nEach row in `items` is an article card as served:\n\n- `id` — the `news_id`; read the article in full with `/news-details`\n- `title`, `image` and `url` (the public article page)\n- `date` — `DD/MM/YYYY`\n- `category` — `{id, name}`\n- `author` — `{id, name, image}`; pass `author.id` to `/author-news`\n- `is_saved` — always `false` without a signed-in user\n- `short_body` — the excerpt; may contain HTML entities\n\nPaging, languages and empty results:\n\n- `pagination.total_pages` is the page count at your `page_size`; `pagination.total_items` is not available on this list (`null`). A `page` past `total_pages` returns an empty `items` list.\n- Each language has its own set of articles, so the same `category_id` can list different articles with `lang=en` and `lang=ar`.\n- An unknown `category_id` returns 404; a category with no articles in the requested language returns an empty list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MotorySuccessResponseSchema" }, "example": { "success": true, "data": { "items": [ { "id": 19386, "title": "National Auto Award 2026 Closes Nominations for Its 14th Edition", "date": "06/10/2026", "category": { "id": 626, "name": "Car News" }, "author": { "id": 13, "name": "Areej Alomari", "image": "https://s3.eu-central-1.amazonaws.com/v3-news.motory.com/news-author/l-1727251642.5266-66f3c4ba808f4_outbound.webp" }, "image": "https://s3.eu-central-1.amazonaws.com/v3-news.motory.com/news/l-1791286070.665-6ac4db36a25b7_outbound.webp", "is_saved": false, "url": "https://ksa.motory.com/en/news/national-auto-award-2026-nominations-close-14th-edition/", "short_body": "The organizing committee of the National Auto Award has confirmed that nominations are now closed across every category and section of the 14th editio..." } ], "pagination": { "page": 1, "page_size": 20, "total_items": null, "total_pages": 17 } } } } } }, "400": { "description": "Bad request — a parameter is missing, malformed or out of range", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MotoryErrorResponseSchema" } } } }, "404": { "description": "Not found — the requested id or link does not exist", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MotoryErrorResponseSchema" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MotoryErrorResponseSchema" } } } }, "503": { "description": "Service busy — retry shortly", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MotoryErrorResponseSchema" } } } } } } }, "/news-search": { "get": { "tags": [ "News" ], "operationId": "searchNews", "description": "Search news articles by keyword, matched against article titles, newest, oldest or most-read first, optionally narrowed to one category, one author or one make; rows are article cards with title, date, category, author, image and excerpt. Open a row's id in /news-details.", "parameters": [ { "schema": { "type": "string", "description": "**Search text.** Required; for example `toyota` or `land cruiser`.\n\nCase-insensitive match on article titles. Write Arabic text with `lang=ar` and English text with `lang=en`: each language searches its own articles. No match returns an empty list.", "example": "toyota", "maxLength": 100 }, "required": true, "description": "**Search text.** Required; for example `toyota` or `land cruiser`.\n\nCase-insensitive match on article titles. Write Arabic text with `lang=ar` and English text with `lang=en`: each language searches its own articles. No match returns an empty list.", "name": "keyword", "in": "query" }, { "schema": { "type": "integer", "description": "**Only articles in this news category.** Optional; one category id.\n\nTake `id` from `/news-categories` called with the same `country`; omit for all categories (the `-1` \"Home\" entry there is not a filter value and is rejected with 400). An id that is not a news category of the selected market is rejected with 400.", "minimum": 1 }, "required": false, "description": "**Only articles in this news category.** Optional; one category id.\n\nTake `id` from `/news-categories` called with the same `country`; omit for all categories (the `-1` \"Home\" entry there is not a filter value and is rejected with 400). An id that is not a news category of the selected market is rejected with 400.", "name": "category_id", "in": "query" }, { "schema": { "type": "integer", "description": "**Only articles by this author.** Optional; one author id.\n\nTake `author.id` from any article row fetched with the same `country`. An id that is not a news author of the selected market is rejected with 400.", "minimum": 1 }, "required": false, "description": "**Only articles by this author.** Optional; one author id.\n\nTake `author.id` from any article row fetched with the same `country`. An id that is not a news author of the selected market is rejected with 400.", "name": "author_id", "in": "query" }, { "schema": { "type": "integer", "description": "**Only articles about this make.** Optional; one make id.\n\nTake ids from `/makes` called with the same `country` (`condition=used` or `new`). A make without matching news returns an empty list; an id that is in neither `/makes` list of the selected market is rejected with 400.", "minimum": 1 }, "required": false, "description": "**Only articles about this make.** Optional; one make id.\n\nTake ids from `/makes` called with the same `country` (`condition=used` or `new`). A make without matching news returns an empty list; an id that is in neither `/makes` list of the selected market is rejected with 400.", "name": "make_id", "in": "query" }, { "schema": { "type": "string", "description": "**Article order.** Optional; defaults to `newest`.\n\n- `newest` — most recently published first\n- `oldest` — earliest published first\n- `most_read` — most-read articles first\n\nEvery filter applies under every order. `most_read` is the order of `/author-news` with `order_by=most_read`: an author's articles narrowed here with `author_id` come in the same order there, except that neighbouring articles can swap places.", "enum": [ "newest", "oldest", "most_read" ], "default": "newest" }, "required": false, "description": "**Article order.** Optional; defaults to `newest`.\n\n- `newest` — most recently published first\n- `oldest` — earliest published first\n- `most_read` — most-read articles first\n\nEvery filter applies under every order. `most_read` is the order of `/author-news` with `order_by=most_read`: an author's articles narrowed here with `author_id` come in the same order there, except that neighbouring articles can swap places.", "name": "sort", "in": "query" }, { "schema": { "type": "string", "description": "**Market to read.** Optional; defaults to `sa`.\n\n- `sa` — Saudi Arabia (prices in SAR)\n- `jo` — Jordan (prices in JOD)\n\nEach market has its own inventory and its own ids (makes, models, cities, body types, dealers, vehicles). Send only ids from a call made with the same `country`. An id from the other market is answered as an unknown id:\n\n- **404** — a lookup by id: every details route, `/models`, `/finance-providers`, and `category_id` on `/category-news` and `/videos`.\n- **400 naming the param** — `make_id`, `model_id` and `finance_provider_id` on `/new-cars` and `/new-car-filters`; `make_id` and `city_id` on `/dealers`; `make_id` and `company_id` on `/offers`; `make_id`, `author_id` and `category_id` as filters of the news lists, and `make_id` on `/videos` (on `/tag-news`, an unknown `author_id` with a tag that is not a make returns an empty list when the tag has articles in the requested `lang`, and 404 otherwise).\n- **Empty result** — every other id filter, for example `body_type_id`, `fuel_type_id`, `transmission_id` or `origin_id` on `/new-cars`, every `/used-cars` and `/used-car-filters` filter, and `dealer_id` on `/dealers`.", "enum": [ "sa", "jo" ], "default": "sa" }, "required": false, "description": "**Market to read.** Optional; defaults to `sa`.\n\n- `sa` — Saudi Arabia (prices in SAR)\n- `jo` — Jordan (prices in JOD)\n\nEach market has its own inventory and its own ids (makes, models, cities, body types, dealers, vehicles). Send only ids from a call made with the same `country`. An id from the other market is answered as an unknown id:\n\n- **404** — a lookup by id: every details route, `/models`, `/finance-providers`, and `category_id` on `/category-news` and `/videos`.\n- **400 naming the param** — `make_id`, `model_id` and `finance_provider_id` on `/new-cars` and `/new-car-filters`; `make_id` and `city_id` on `/dealers`; `make_id` and `company_id` on `/offers`; `make_id`, `author_id` and `category_id` as filters of the news lists, and `make_id` on `/videos` (on `/tag-news`, an unknown `author_id` with a tag that is not a make returns an empty list when the tag has articles in the requested `lang`, and 404 otherwise).\n- **Empty result** — every other id filter, for example `body_type_id`, `fuel_type_id`, `transmission_id` or `origin_id` on `/new-cars`, every `/used-cars` and `/used-car-filters` filter, and `dealer_id` on `/dealers`.", "name": "country", "in": "query" }, { "schema": { "type": "string", "description": "**Language of the news — and which articles you get.** Optional; defaults to `en`.\n\n- `en` — English\n- `ar` — Arabic\n\nNews is written separately in each language:\n\n- Each language has its own set of articles, and some articles and categories exist in one language only.\n- Ids are the same in both languages, but a list can hold different articles in each.\n- An article published in one language only returns 404 in the other; the message names the `lang` to use.", "enum": [ "en", "ar" ], "default": "en" }, "required": false, "description": "**Language of the news — and which articles you get.** Optional; defaults to `en`.\n\n- `en` — English\n- `ar` — Arabic\n\nNews is written separately in each language:\n\n- Each language has its own set of articles, and some articles and categories exist in one language only.\n- Ids are the same in both languages, but a list can hold different articles in each.\n- An article published in one language only returns 404 in the other; the message names the `lang` to use.", "name": "lang", "in": "query" }, { "schema": { "type": "integer", "description": "**Page number, starting at 1.** Optional; defaults to `1`.\n\nKeep `page_size` fixed while paging and stop at `pagination.total_pages`. A `page` beyond the last page returns an empty `items` list.", "minimum": 1, "maximum": 10000, "default": 1 }, "required": false, "description": "**Page number, starting at 1.** Optional; defaults to `1`.\n\nKeep `page_size` fixed while paging and stop at `pagination.total_pages`. A `page` beyond the last page returns an empty `items` list.", "name": "page", "in": "query" }, { "schema": { "type": "integer", "description": "**Results per page.** Optional; defaults to `20`, accepts 1–50.\n\nValues above 50 are rejected with 400. Keep the same `page_size` on every page of one search so pages neither overlap nor skip results.", "minimum": 1, "maximum": 50, "default": 20 }, "required": false, "description": "**Results per page.** Optional; defaults to `20`, accepts 1–50.\n\nValues above 50 are rejected with 400. Keep the same `page_size` on every page of one search so pages neither overlap nor skip results.", "name": "page_size", "in": "query" } ], "responses": { "200": { "description": "**Keyword search over news article titles**, newest first by default (or oldest or most-read first), optionally narrowed to one category, one author and/or one make. Every filter sent must match.\n\nEach row in `items` is an article card as served:\n\n- `id` — the `news_id`; read the article in full with `/news-details`\n- `title`, `image` and `url` (the public article page)\n- `date` — `DD/MM/YYYY`\n- `category` — `{id, name}`\n- `author` — `{id, name, image}`; pass `author.id` to `/author-news`\n- `is_saved` — always `false` without a signed-in user\n- `short_body` — the excerpt; may contain HTML entities\n\nPaging and empty results:\n\n- `pagination.total_pages` is the page count at your `page_size`; `pagination.total_items` is not available on this list (`null`). A `page` past `total_pages` returns an empty `items` list.\n- No match returns an empty list. An unknown `category_id`, `author_id` or `make_id` filter is rejected with 400.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MotorySuccessResponseSchema" }, "example": { "success": true, "data": { "items": [ { "id": 19299, "title": "Toyota Land Cruiser FJ 2026: Specs, Grades & Price in the Middle East", "date": "09/09/2026", "category": { "id": 626, "name": "Car News" }, "author": { "id": 3, "name": "Motory Editorial", "image": "https://s3.eu-central-1.amazonaws.com/v3-news.motory.com/news-author/l-1619350234.7454-608552dab5f8e.webp" }, "image": "https://s3.eu-central-1.amazonaws.com/v3-news.motory.com/news/l-1788946835.9984-6aa12993f3bea_outbound.webp", "is_saved": false, "url": "https://ksa.motory.com/en/news/toyota-land-cruiser-fj-launch/", "short_body": "Toyota has revealed the all-new Land Cruiser FJ for the Middle East, adding a fresh member to the storied Land Cruiser lineup and putting the nameplat..." } ], "pagination": { "page": 1, "page_size": 20, "total_items": null, "total_pages": 4 } } } } } }, "400": { "description": "Bad request — a parameter is missing, malformed or out of range", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MotoryErrorResponseSchema" } } } }, "404": { "description": "Not found — the requested id or link does not exist", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MotoryErrorResponseSchema" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MotoryErrorResponseSchema" } } } }, "503": { "description": "Service busy — retry shortly", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MotoryErrorResponseSchema" } } } } } } }, "/news-details": { "get": { "tags": [ "News" ], "operationId": "getNewsDetails", "description": "Read one news article in full: HTML body, gallery, author, tags and related articles. Takes a news_id, the id of an article row from /category-news, /news-search, /tag-news, /author-news or /most-read-news.", "parameters": [ { "schema": { "type": "integer", "description": "**News article id.** Required; for example `19386` (in `sa`).\n\nTake `id` from any article row (`/category-news`, `/news-search`, `/tag-news`, `/author-news`, `/most-read-news`, or `related_topics` here) fetched with the same `country`. Article ids differ between markets; an unknown id returns 404.", "minimum": 1, "example": 19386 }, "required": true, "description": "**News article id.** Required; for example `19386` (in `sa`).\n\nTake `id` from any article row (`/category-news`, `/news-search`, `/tag-news`, `/author-news`, `/most-read-news`, or `related_topics` here) fetched with the same `country`. Article ids differ between markets; an unknown id returns 404.", "name": "news_id", "in": "query" }, { "schema": { "type": "string", "description": "**Market to read.** Optional; defaults to `sa`.\n\n- `sa` — Saudi Arabia (prices in SAR)\n- `jo` — Jordan (prices in JOD)\n\nEach market has its own inventory and its own ids (makes, models, cities, body types, dealers, vehicles). Send only ids from a call made with the same `country`. An id from the other market is answered as an unknown id:\n\n- **404** — a lookup by id: every details route, `/models`, `/finance-providers`, and `category_id` on `/category-news` and `/videos`.\n- **400 naming the param** — `make_id`, `model_id` and `finance_provider_id` on `/new-cars` and `/new-car-filters`; `make_id` and `city_id` on `/dealers`; `make_id` and `company_id` on `/offers`; `make_id`, `author_id` and `category_id` as filters of the news lists, and `make_id` on `/videos` (on `/tag-news`, an unknown `author_id` with a tag that is not a make returns an empty list when the tag has articles in the requested `lang`, and 404 otherwise).\n- **Empty result** — every other id filter, for example `body_type_id`, `fuel_type_id`, `transmission_id` or `origin_id` on `/new-cars`, every `/used-cars` and `/used-car-filters` filter, and `dealer_id` on `/dealers`.", "enum": [ "sa", "jo" ], "default": "sa" }, "required": false, "description": "**Market to read.** Optional; defaults to `sa`.\n\n- `sa` — Saudi Arabia (prices in SAR)\n- `jo` — Jordan (prices in JOD)\n\nEach market has its own inventory and its own ids (makes, models, cities, body types, dealers, vehicles). Send only ids from a call made with the same `country`. An id from the other market is answered as an unknown id:\n\n- **404** — a lookup by id: every details route, `/models`, `/finance-providers`, and `category_id` on `/category-news` and `/videos`.\n- **400 naming the param** — `make_id`, `model_id` and `finance_provider_id` on `/new-cars` and `/new-car-filters`; `make_id` and `city_id` on `/dealers`; `make_id` and `company_id` on `/offers`; `make_id`, `author_id` and `category_id` as filters of the news lists, and `make_id` on `/videos` (on `/tag-news`, an unknown `author_id` with a tag that is not a make returns an empty list when the tag has articles in the requested `lang`, and 404 otherwise).\n- **Empty result** — every other id filter, for example `body_type_id`, `fuel_type_id`, `transmission_id` or `origin_id` on `/new-cars`, every `/used-cars` and `/used-car-filters` filter, and `dealer_id` on `/dealers`.", "name": "country", "in": "query" }, { "schema": { "type": "string", "description": "**Language of the news — and which articles you get.** Optional; defaults to `en`.\n\n- `en` — English\n- `ar` — Arabic\n\nNews is written separately in each language:\n\n- Each language has its own set of articles, and some articles and categories exist in one language only.\n- Ids are the same in both languages, but a list can hold different articles in each.\n- An article published in one language only returns 404 in the other; the message names the `lang` to use.", "enum": [ "en", "ar" ], "default": "en" }, "required": false, "description": "**Language of the news — and which articles you get.** Optional; defaults to `en`.\n\n- `en` — English\n- `ar` — Arabic\n\nNews is written separately in each language:\n\n- Each language has its own set of articles, and some articles and categories exist in one language only.\n- Ids are the same in both languages, but a list can hold different articles in each.\n- An article published in one language only returns 404 in the other; the message names the `lang` to use.", "name": "lang", "in": "query" } ], "responses": { "200": { "description": "**One news article in full.** Fields as served:\n\n- `title`, `category` and `author` `{id, name, image}`\n- `date` — `DD/MM/YYYY`\n- `description` — the article body as HTML, exactly as published\n- `images_only` and `images_with_text` — the gallery; `null` when absent\n- `video` — `null` when absent\n- `share_link` and `currency`\n- `related_new_vehicles` — names (and, when present, lists) the new cars the article is about\n- `related_news` — the article's further-reading list as served\n- `tags` — the article's own tags; pass a tag `id` to `/tag-news`\n- `related_topics` — articles related to this one (the same row shape as `/category-news`)\n\nAn unknown `news_id` returns 404. An article published in the other language only also returns 404, with a message naming the `lang` to request it with.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MotorySuccessResponseSchema" }, "example": { "success": true, "data": { "id": 19386, "video": null, "images_only": [ "https://s3.eu-central-1.amazonaws.com/v3-news.motory.com/news/l-1791286070.665-6ac4db36a25b7_outbound.webp" ], "images_with_text": null, "category": { "id": 626, "name": "Car News" }, "title": "National Auto Award 2026 Closes Nominations for Its 14th Edition", "author": { "id": 13, "name": "Areej Alomari", "image": "https://s3.eu-central-1.amazonaws.com/v3-news.motory.com/news-author/l-1727251642.5266-66f3c4ba808f4_outbound.webp" }, "date": "06/10/2026", "description": "

The organizing committee of the National Auto Award has confirmed that nominations are now closed across every category and section of the 14th edition (2026). The winners will be announced and honored at the final ceremony, set for mid-November in Jeddah.

\r\n\r\n

The award is the first and only one of its kind in the Middle East. It is organized and run by PR Arabia, supported by the Saudi Automobile and Motorcycle Federation (SAMF), with JB Finance as its strategic partner.

\r\n\r\n

Chinese Models Take the Lead as Electric and Hybrid Vehicles Gain Ground

\r\n\r\n

This year's nominations reveal a clear change in local market trends. Tech-focused electric and hybrid models topped the list, backed by advanced powertrain technologies such as PHEV and REEV. Traditional categories, especially Japanese and Korean, saw a noticeable decline in nominations. Chinese models, on the other hand, kept rising strongly and steadily, strengthening their market share in the Kingdom amid fierce competition between manufacturers and their distributors. This edition also recorded higher participation from luxury and supercar categories.

\r\n\r\n

A Landmark Year for the Kingdom's Automotive Sector

\r\n\r\n

2026 has brought pivotal events to the Kingdom's automotive sector. They include the launch of advanced models built on modern engine systems and the hosting of global motorsport championships such as the Dakar Rally and a round of the Formula E World Championship. The most prominent event, globally and locally, was the official launch announcement of the national brand "CEER" on September 21.

\r\n\r\n

Over 25 Categories and Surprises on the Way

\r\n\r\n

Award Secretary-General Walid Karanouh explained that the deadline for closing the nomination platform was extended to give as many participants as possible the chance to enter, and to accommodate new models whose arrival was delayed by global shipping conditions.

\r\n\r\n

Karanouh noted that the award hit its target of more than 25 categories, covering vehicles, special awards, and motorsport awards. He also revealed that surprises and new categories will be introduced for the first time at the final ceremony.

\r\n\r\n

He added: "We constantly strive to keep pace with technological advancement to select the best across all categories, while keeping up with the latest developments in the automotive world so that the award remains comprehensive and supportive of the sector, continuing its role in celebrating excellence and innovation while highlighting influential individuals, companies, and initiatives in the Kingdom." Finally, you can check out the latest car news by visiting Motory Cars News section.

\r\n", "related_new_vehicles": { "section_title": "Newest Toyota Cars", "section_link": "https://ksa.motory.com/en/new-cars/toyota/", "data": [ { "vehicle_id": 281200, "make_name": "Toyota", "make_id": 90, "model_name": "Hilux", "model_id": 408, "grade": "GL 2.7 4x4 MT", "title": "Toyota Hilux GL 2.7 4x4 MT 2027", "year": 2027, "price": 131505, "price_text": "Asking Price", "monthly_payment": null, "finance_available": true, "image": "https://s3.eu-central-1.amazonaws.com/v3-ncg.motory.com/vehicle-new/l-1790065202.8693-6ab23a32d438b_outbound.webp", "icon": "https://s3.eu-central-1.amazonaws.com/v3-common.motory.com/taxonomy/l-1669878465.8496-638852c1cf6f3.webp" } ] }, "related_news": [ { "id": 4276, "title": "Unprecedented: Ford F-Series Achieves 40 Consecutive Years as America’s Best Selling Truck", "date": "05/01/2017", "category": { "id": 626, "name": "Car News" }, "author": { "id": 3, "name": "Motory Editorial", "image": "https://s3.eu-central-1.amazonaws.com/v3-news.motory.com/news-author/l-1619350234.7454-608552dab5f8e.webp" }, "image": "https://s3.eu-central-1.amazonaws.com/v3-news.motory.com/news/l-1605488357.7856-5fb1cee5bfca7.webp", "is_saved": false, "url": "https://ksa.motory.com/en/news/?filter1=unprecedented-ford-f-series-achieves-40-consecutive-years-as-america%E2%80%99s-best-selling-truck-4276", "short_body": "Ford, America’s truck leader, is celebrating a major milestone as F-Series now reigns as the top-selling truck in the country for 40 consecutive years..." } ], "currency": "SR", "share_link": "https://ksa.motory.com/en/news/national-auto-award-2026-nominations-close-14th-edition/", "is_saved": false, "tags": [ { "id": 8468, "name": "Latest Updates" } ], "related_topics": [ { "id": 19370, "title": "Nissan Saudi Arabia expands counterfeit parts awareness", "date": "01/10/2026", "category": { "id": 629, "name": "Local News" }, "author": { "id": 3, "name": "Motory Editorial", "image": "https://s3.eu-central-1.amazonaws.com/v3-news.motory.com/news-author/l-1619350234.7454-608552dab5f8e.webp" }, "image": "https://s3.eu-central-1.amazonaws.com/v3-news.motory.com/news/l-1790840810.3073-6abe0fea4b064.webp", "is_saved": false, "url": "https://ksa.motory.com/en/news/nissan-counterfeit-parts-awareness/", "short_body": "Nissan Saudi Arabia focuses on raising awareness of the consequences of using counterfeit spare parts, given the risks they may pose to vehicle perfor..." } ] } } } } }, "400": { "description": "Bad request — a parameter is missing, malformed or out of range", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MotoryErrorResponseSchema" } } } }, "404": { "description": "Not found — the requested id or link does not exist", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MotoryErrorResponseSchema" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MotoryErrorResponseSchema" } } } }, "503": { "description": "Service busy — retry shortly", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MotoryErrorResponseSchema" } } } } } } }, "/author-details": { "get": { "tags": [ "News" ], "operationId": "getNewsAuthorDetails", "description": "Read a news author's profile: biography, job title, credentials, social links and topics. Takes an author_id, the author id of an article row; list their articles with /author-news and tags with /author-tags.", "parameters": [ { "schema": { "type": "integer", "description": "**News author id.** Required; for example `13`.\n\nTake `author.id` from any article row (`/category-news`, `/news-search`, `/tag-news`, `/most-read-news`) or from `/news-details`, fetched with the same `country`. Author ids differ between markets; an unknown id returns 404.", "minimum": 1, "example": 13 }, "required": true, "description": "**News author id.** Required; for example `13`.\n\nTake `author.id` from any article row (`/category-news`, `/news-search`, `/tag-news`, `/most-read-news`) or from `/news-details`, fetched with the same `country`. Author ids differ between markets; an unknown id returns 404.", "name": "author_id", "in": "query" }, { "schema": { "type": "string", "description": "**Market to read.** Optional; defaults to `sa`.\n\n- `sa` — Saudi Arabia (prices in SAR)\n- `jo` — Jordan (prices in JOD)\n\nEach market has its own inventory and its own ids (makes, models, cities, body types, dealers, vehicles). Send only ids from a call made with the same `country`. An id from the other market is answered as an unknown id:\n\n- **404** — a lookup by id: every details route, `/models`, `/finance-providers`, and `category_id` on `/category-news` and `/videos`.\n- **400 naming the param** — `make_id`, `model_id` and `finance_provider_id` on `/new-cars` and `/new-car-filters`; `make_id` and `city_id` on `/dealers`; `make_id` and `company_id` on `/offers`; `make_id`, `author_id` and `category_id` as filters of the news lists, and `make_id` on `/videos` (on `/tag-news`, an unknown `author_id` with a tag that is not a make returns an empty list when the tag has articles in the requested `lang`, and 404 otherwise).\n- **Empty result** — every other id filter, for example `body_type_id`, `fuel_type_id`, `transmission_id` or `origin_id` on `/new-cars`, every `/used-cars` and `/used-car-filters` filter, and `dealer_id` on `/dealers`.", "enum": [ "sa", "jo" ], "default": "sa" }, "required": false, "description": "**Market to read.** Optional; defaults to `sa`.\n\n- `sa` — Saudi Arabia (prices in SAR)\n- `jo` — Jordan (prices in JOD)\n\nEach market has its own inventory and its own ids (makes, models, cities, body types, dealers, vehicles). Send only ids from a call made with the same `country`. An id from the other market is answered as an unknown id:\n\n- **404** — a lookup by id: every details route, `/models`, `/finance-providers`, and `category_id` on `/category-news` and `/videos`.\n- **400 naming the param** — `make_id`, `model_id` and `finance_provider_id` on `/new-cars` and `/new-car-filters`; `make_id` and `city_id` on `/dealers`; `make_id` and `company_id` on `/offers`; `make_id`, `author_id` and `category_id` as filters of the news lists, and `make_id` on `/videos` (on `/tag-news`, an unknown `author_id` with a tag that is not a make returns an empty list when the tag has articles in the requested `lang`, and 404 otherwise).\n- **Empty result** — every other id filter, for example `body_type_id`, `fuel_type_id`, `transmission_id` or `origin_id` on `/new-cars`, every `/used-cars` and `/used-car-filters` filter, and `dealer_id` on `/dealers`.", "name": "country", "in": "query" }, { "schema": { "type": "string", "description": "**Language of the news — and which articles you get.** Optional; defaults to `en`.\n\n- `en` — English\n- `ar` — Arabic\n\nNews is written separately in each language:\n\n- Each language has its own set of articles, and some articles and categories exist in one language only.\n- Ids are the same in both languages, but a list can hold different articles in each.\n- An article published in one language only returns 404 in the other; the message names the `lang` to use.", "enum": [ "en", "ar" ], "default": "en" }, "required": false, "description": "**Language of the news — and which articles you get.** Optional; defaults to `en`.\n\n- `en` — English\n- `ar` — Arabic\n\nNews is written separately in each language:\n\n- Each language has its own set of articles, and some articles and categories exist in one language only.\n- Ids are the same in both languages, but a list can hold different articles in each.\n- An article published in one language only returns 404 in the other; the message names the `lang` to use.", "name": "lang", "in": "query" } ], "responses": { "200": { "description": "**A news author's profile**, as published:\n\n- `info` — `id`, `name`, `logo`, `job_title`, `intro` (the biography) and `slug_en` / `slug_ar`\n- `tags` — the topics the author covers, each `{id, name, url}`; pass `id` to `/tag-news`\n- `certificates` — `degree`, `major` and `label`\n- `social_media` — `platform`, `link` and `icon`\n\nList the author's articles with `/author-news` and the full tag list with `/author-tags`. An unknown `author_id` returns 404.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MotorySuccessResponseSchema" }, "example": { "success": true, "data": { "info": { "id": 13, "logo": "https://s3.eu-central-1.amazonaws.com/v3-news.motory.com/news-author/l-1727251642.5266-66f3c4ba808f4_outbound.webp", "name": "Areej Alomari", "intro": "is a skilled bilingual Senior Content Writer with over 5 years of experience in the automotive industry. She turns complex topics into engaging content. Her passion for cars drives her work, creating content that appeals to both automotive enthusiasts and industry professionals.", "job_title": "Senior Content Writer", "slug_ar": "أريج-العمري", "slug_en": "areej-alomari" }, "tags": [ { "id": 80, "name": "Genesis", "url": "https://ksa.motory.com/en/news/genesis/" } ], "certificates": [ { "degree": "Bachelor's degree", "major": "Faculty of Arts", "label": "Bachelor's degree in Faculty of Arts" } ], "social_media": [ { "platform": "linkedin", "link": "https://www.linkedin.com/in/areej-alomari-18166a203/", "icon": "https://ksa.motory.com/images/author_social_icons/linkedin.png" } ] } } } } }, "400": { "description": "Bad request — a parameter is missing, malformed or out of range", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MotoryErrorResponseSchema" } } } }, "404": { "description": "Not found — the requested id or link does not exist", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MotoryErrorResponseSchema" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MotoryErrorResponseSchema" } } } }, "503": { "description": "Service busy — retry shortly", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MotoryErrorResponseSchema" } } } } } } }, "/author-news": { "get": { "tags": [ "News" ], "operationId": "getNewsByAuthor", "description": "List one author's news articles, newest, oldest or most-read first, optionally narrowed to one category, one make or a title text, as article cards. Takes an author_id from an article row's author id; open a row's id in /news-details.", "parameters": [ { "schema": { "type": "integer", "description": "**News author id.** Required; for example `13`.\n\nTake `author.id` from any article row (`/category-news`, `/news-search`, `/tag-news`, `/most-read-news`) or from `/news-details`, fetched with the same `country`. Author ids differ between markets; an unknown id returns 404.", "minimum": 1, "example": 13 }, "required": true, "description": "**News author id.** Required; for example `13`.\n\nTake `author.id` from any article row (`/category-news`, `/news-search`, `/tag-news`, `/most-read-news`) or from `/news-details`, fetched with the same `country`. Author ids differ between markets; an unknown id returns 404.", "name": "author_id", "in": "query" }, { "schema": { "type": "string", "description": "**Article order.** Optional; omitted means `latest` (or the most-read order with `sort=most_read`).\n\n- `latest` — by publication date; `sort` picks newest or oldest first\n- `most_read` — most-read articles first (the same as `sort=most_read`)\n\n`order_by=latest` together with `sort=most_read` is rejected with 400: the two orders contradict each other.", "enum": [ "latest", "most_read" ] }, "required": false, "description": "**Article order.** Optional; omitted means `latest` (or the most-read order with `sort=most_read`).\n\n- `latest` — by publication date; `sort` picks newest or oldest first\n- `most_read` — most-read articles first (the same as `sort=most_read`)\n\n`order_by=latest` together with `sort=most_read` is rejected with 400: the two orders contradict each other.", "name": "order_by", "in": "query" }, { "schema": { "type": "string", "description": "**Article order**, as on the other news lists. Optional; omitted means `newest` (or the most-read order with `order_by=most_read`).\n\n- `newest` — most recently published first\n- `oldest` — earliest published first\n- `most_read` — most-read articles first (the same as `order_by=most_read`)\n\n`newest` or `oldest` together with `order_by=most_read` is rejected with 400: the most-read order has no date direction. `most_read` together with `order_by=latest` is rejected with 400 too.", "enum": [ "newest", "oldest", "most_read" ] }, "required": false, "description": "**Article order**, as on the other news lists. Optional; omitted means `newest` (or the most-read order with `order_by=most_read`).\n\n- `newest` — most recently published first\n- `oldest` — earliest published first\n- `most_read` — most-read articles first (the same as `order_by=most_read`)\n\n`newest` or `oldest` together with `order_by=most_read` is rejected with 400: the most-read order has no date direction. `most_read` together with `order_by=latest` is rejected with 400 too.", "name": "sort", "in": "query" }, { "schema": { "type": "integer", "description": "**Only articles in this news category.** Optional; one category id.\n\nTake `id` from `/news-categories` called with the same `country`; omit for all categories (the `-1` \"Home\" entry there is not a filter value and is rejected with 400). An id that is not a news category of the selected market is rejected with 400.", "minimum": 1 }, "required": false, "description": "**Only articles in this news category.** Optional; one category id.\n\nTake `id` from `/news-categories` called with the same `country`; omit for all categories (the `-1` \"Home\" entry there is not a filter value and is rejected with 400). An id that is not a news category of the selected market is rejected with 400.", "name": "category_id", "in": "query" }, { "schema": { "type": "integer", "description": "**Only articles about this make.** Optional; one make id.\n\nTake ids from `/makes` called with the same `country` (`condition=used` or `new`). A make without matching news returns an empty list; an id that is in neither `/makes` list of the selected market is rejected with 400.", "minimum": 1 }, "required": false, "description": "**Only articles about this make.** Optional; one make id.\n\nTake ids from `/makes` called with the same `country` (`condition=used` or `new`). A make without matching news returns an empty list; an id that is in neither `/makes` list of the selected market is rejected with 400.", "name": "make_id", "in": "query" }, { "schema": { "type": "string", "description": "**Only articles whose title contains this text**, case-insensitive. Optional; for example `toyota`.\n\nWrite Arabic text with `lang=ar` and English text with `lang=en`. No match returns an empty list.", "maxLength": 100 }, "required": false, "description": "**Only articles whose title contains this text**, case-insensitive. Optional; for example `toyota`.\n\nWrite Arabic text with `lang=ar` and English text with `lang=en`. No match returns an empty list.", "name": "keyword", "in": "query" }, { "schema": { "type": "string", "description": "**Market to read.** Optional; defaults to `sa`.\n\n- `sa` — Saudi Arabia (prices in SAR)\n- `jo` — Jordan (prices in JOD)\n\nEach market has its own inventory and its own ids (makes, models, cities, body types, dealers, vehicles). Send only ids from a call made with the same `country`. An id from the other market is answered as an unknown id:\n\n- **404** — a lookup by id: every details route, `/models`, `/finance-providers`, and `category_id` on `/category-news` and `/videos`.\n- **400 naming the param** — `make_id`, `model_id` and `finance_provider_id` on `/new-cars` and `/new-car-filters`; `make_id` and `city_id` on `/dealers`; `make_id` and `company_id` on `/offers`; `make_id`, `author_id` and `category_id` as filters of the news lists, and `make_id` on `/videos` (on `/tag-news`, an unknown `author_id` with a tag that is not a make returns an empty list when the tag has articles in the requested `lang`, and 404 otherwise).\n- **Empty result** — every other id filter, for example `body_type_id`, `fuel_type_id`, `transmission_id` or `origin_id` on `/new-cars`, every `/used-cars` and `/used-car-filters` filter, and `dealer_id` on `/dealers`.", "enum": [ "sa", "jo" ], "default": "sa" }, "required": false, "description": "**Market to read.** Optional; defaults to `sa`.\n\n- `sa` — Saudi Arabia (prices in SAR)\n- `jo` — Jordan (prices in JOD)\n\nEach market has its own inventory and its own ids (makes, models, cities, body types, dealers, vehicles). Send only ids from a call made with the same `country`. An id from the other market is answered as an unknown id:\n\n- **404** — a lookup by id: every details route, `/models`, `/finance-providers`, and `category_id` on `/category-news` and `/videos`.\n- **400 naming the param** — `make_id`, `model_id` and `finance_provider_id` on `/new-cars` and `/new-car-filters`; `make_id` and `city_id` on `/dealers`; `make_id` and `company_id` on `/offers`; `make_id`, `author_id` and `category_id` as filters of the news lists, and `make_id` on `/videos` (on `/tag-news`, an unknown `author_id` with a tag that is not a make returns an empty list when the tag has articles in the requested `lang`, and 404 otherwise).\n- **Empty result** — every other id filter, for example `body_type_id`, `fuel_type_id`, `transmission_id` or `origin_id` on `/new-cars`, every `/used-cars` and `/used-car-filters` filter, and `dealer_id` on `/dealers`.", "name": "country", "in": "query" }, { "schema": { "type": "string", "description": "**Language of the news — and which articles you get.** Optional; defaults to `en`.\n\n- `en` — English\n- `ar` — Arabic\n\nNews is written separately in each language:\n\n- Each language has its own set of articles, and some articles and categories exist in one language only.\n- Ids are the same in both languages, but a list can hold different articles in each.\n- An article published in one language only returns 404 in the other; the message names the `lang` to use.", "enum": [ "en", "ar" ], "default": "en" }, "required": false, "description": "**Language of the news — and which articles you get.** Optional; defaults to `en`.\n\n- `en` — English\n- `ar` — Arabic\n\nNews is written separately in each language:\n\n- Each language has its own set of articles, and some articles and categories exist in one language only.\n- Ids are the same in both languages, but a list can hold different articles in each.\n- An article published in one language only returns 404 in the other; the message names the `lang` to use.", "name": "lang", "in": "query" }, { "schema": { "type": "integer", "description": "**Page number, starting at 1.** Optional; defaults to `1`.\n\nKeep `page_size` fixed while paging and stop at `pagination.total_pages`. A `page` beyond the last page returns an empty `items` list.", "minimum": 1, "maximum": 10000, "default": 1 }, "required": false, "description": "**Page number, starting at 1.** Optional; defaults to `1`.\n\nKeep `page_size` fixed while paging and stop at `pagination.total_pages`. A `page` beyond the last page returns an empty `items` list.", "name": "page", "in": "query" }, { "schema": { "type": "integer", "description": "**Results per page.** Optional; defaults to `20`, accepts 1–50.\n\nValues above 50 are rejected with 400. Keep the same `page_size` on every page of one search so pages neither overlap nor skip results.", "minimum": 1, "maximum": 50, "default": 20 }, "required": false, "description": "**Results per page.** Optional; defaults to `20`, accepts 1–50.\n\nValues above 50 are rejected with 400. Keep the same `page_size` on every page of one search so pages neither overlap nor skip results.", "name": "page_size", "in": "query" } ], "responses": { "200": { "description": "**One author's news articles**, newest, oldest or most-read first, optionally narrowed to one category, one make or a title text. Filters combine: every one must match.\n\nEach row in `items` is an article card as served:\n\n- `id` — the `news_id`; read the article in full with `/news-details`\n- `title`, `image` and `url`\n- `date` — `DD/MM/YYYY`\n- `category` — `{id, name, url}`\n- `author` — `{id, name, image, url}`\n- `is_saved`\n- `description` — the excerpt\n\nPaging, languages and empty results:\n\n- `pagination.total_pages` is the page count at your `page_size`; `pagination.total_items` is not available on this list (`null`). A `page` past `total_pages` returns an empty `items` list.\n- Each language has its own set of articles, so the same `author_id` can list different articles with `lang=en` and `lang=ar`.\n- An unknown `author_id` returns 404; an author with no articles in the requested language returns an empty list. An unknown `category_id` or `make_id` filter is rejected with 400.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MotorySuccessResponseSchema" }, "example": { "success": true, "data": { "items": [ { "id": 19386, "title": "National Auto Award 2026 Closes Nominations for Its 14th Edition", "date": "06/10/2026", "category": { "id": 626, "name": "Car News", "url": "https://ksa.motory.com/en/news/cars-news/" }, "author": { "id": 13, "name": "Areej Alomari", "image": "https://s3.eu-central-1.amazonaws.com/v3-news.motory.com/news-author/l-1727251642.5266-66f3c4ba808f4_outbound.webp", "url": "https://ksa.motory.com/en/author/areej-alomari/" }, "image": "https://s3.eu-central-1.amazonaws.com/v3-news.motory.com/news/l-1791286070.665-6ac4db36a25b7_outbound.webp", "is_saved": false, "url": "https://ksa.motory.com/en/news/national-auto-award-2026-nominations-close-14th-edition/", "description": "The organizing committee of the National Auto Award has confirmed that nominations are now closed across every category and section of the 14th editio..." } ], "pagination": { "page": 1, "page_size": 20, "total_items": null, "total_pages": 7 } } } } } }, "400": { "description": "Bad request — a parameter is missing, malformed or out of range", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MotoryErrorResponseSchema" } } } }, "404": { "description": "Not found — the requested id or link does not exist", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MotoryErrorResponseSchema" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MotoryErrorResponseSchema" } } } }, "503": { "description": "Service busy — retry shortly", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MotoryErrorResponseSchema" } } } } } } }, "/author-tags": { "get": { "tags": [ "News" ], "operationId": "listNewsAuthorTags", "description": "List the tags an author writes under (makes, body types, topics), optionally narrowed by a name fragment. Takes an author_id from an article row; pass a tag id to /tag-news for its articles.", "parameters": [ { "schema": { "type": "integer", "description": "**News author id.** Required; for example `13`.\n\nTake `author.id` from any article row (`/category-news`, `/news-search`, `/tag-news`, `/most-read-news`) or from `/news-details`, fetched with the same `country`. Author ids differ between markets; an unknown id returns 404.", "minimum": 1, "example": 13 }, "required": true, "description": "**News author id.** Required; for example `13`.\n\nTake `author.id` from any article row (`/category-news`, `/news-search`, `/tag-news`, `/most-read-news`) or from `/news-details`, fetched with the same `country`. Author ids differ between markets; an unknown id returns 404.", "name": "author_id", "in": "query" }, { "schema": { "type": "string", "description": "**Tag name filter.** Optional; for example `suv` or `mazda`.\n\nKeeps tags whose name contains the text, case-insensitive. No match returns an empty list.", "maxLength": 100 }, "required": false, "description": "**Tag name filter.** Optional; for example `suv` or `mazda`.\n\nKeeps tags whose name contains the text, case-insensitive. No match returns an empty list.", "name": "keyword", "in": "query" }, { "schema": { "type": "string", "description": "**Market to read.** Optional; defaults to `sa`.\n\n- `sa` — Saudi Arabia (prices in SAR)\n- `jo` — Jordan (prices in JOD)\n\nEach market has its own inventory and its own ids (makes, models, cities, body types, dealers, vehicles). Send only ids from a call made with the same `country`. An id from the other market is answered as an unknown id:\n\n- **404** — a lookup by id: every details route, `/models`, `/finance-providers`, and `category_id` on `/category-news` and `/videos`.\n- **400 naming the param** — `make_id`, `model_id` and `finance_provider_id` on `/new-cars` and `/new-car-filters`; `make_id` and `city_id` on `/dealers`; `make_id` and `company_id` on `/offers`; `make_id`, `author_id` and `category_id` as filters of the news lists, and `make_id` on `/videos` (on `/tag-news`, an unknown `author_id` with a tag that is not a make returns an empty list when the tag has articles in the requested `lang`, and 404 otherwise).\n- **Empty result** — every other id filter, for example `body_type_id`, `fuel_type_id`, `transmission_id` or `origin_id` on `/new-cars`, every `/used-cars` and `/used-car-filters` filter, and `dealer_id` on `/dealers`.", "enum": [ "sa", "jo" ], "default": "sa" }, "required": false, "description": "**Market to read.** Optional; defaults to `sa`.\n\n- `sa` — Saudi Arabia (prices in SAR)\n- `jo` — Jordan (prices in JOD)\n\nEach market has its own inventory and its own ids (makes, models, cities, body types, dealers, vehicles). Send only ids from a call made with the same `country`. An id from the other market is answered as an unknown id:\n\n- **404** — a lookup by id: every details route, `/models`, `/finance-providers`, and `category_id` on `/category-news` and `/videos`.\n- **400 naming the param** — `make_id`, `model_id` and `finance_provider_id` on `/new-cars` and `/new-car-filters`; `make_id` and `city_id` on `/dealers`; `make_id` and `company_id` on `/offers`; `make_id`, `author_id` and `category_id` as filters of the news lists, and `make_id` on `/videos` (on `/tag-news`, an unknown `author_id` with a tag that is not a make returns an empty list when the tag has articles in the requested `lang`, and 404 otherwise).\n- **Empty result** — every other id filter, for example `body_type_id`, `fuel_type_id`, `transmission_id` or `origin_id` on `/new-cars`, every `/used-cars` and `/used-car-filters` filter, and `dealer_id` on `/dealers`.", "name": "country", "in": "query" }, { "schema": { "type": "string", "description": "**Language of the news — and which articles you get.** Optional; defaults to `en`.\n\n- `en` — English\n- `ar` — Arabic\n\nNews is written separately in each language:\n\n- Each language has its own set of articles, and some articles and categories exist in one language only.\n- Ids are the same in both languages, but a list can hold different articles in each.\n- An article published in one language only returns 404 in the other; the message names the `lang` to use.", "enum": [ "en", "ar" ], "default": "en" }, "required": false, "description": "**Language of the news — and which articles you get.** Optional; defaults to `en`.\n\n- `en` — English\n- `ar` — Arabic\n\nNews is written separately in each language:\n\n- Each language has its own set of articles, and some articles and categories exist in one language only.\n- Ids are the same in both languages, but a list can hold different articles in each.\n- An article published in one language only returns 404 in the other; the message names the `lang` to use.", "name": "lang", "in": "query" }, { "schema": { "type": "integer", "description": "**Page number, starting at 1.** Optional; defaults to `1`.\n\nKeep `page_size` fixed while paging and stop at `pagination.total_pages`. A `page` beyond the last page returns an empty `items` list.", "minimum": 1, "maximum": 10000, "default": 1 }, "required": false, "description": "**Page number, starting at 1.** Optional; defaults to `1`.\n\nKeep `page_size` fixed while paging and stop at `pagination.total_pages`. A `page` beyond the last page returns an empty `items` list.", "name": "page", "in": "query" }, { "schema": { "type": "integer", "description": "**Results per page.** Optional; defaults to `20`, accepts 1–50.\n\nValues above 50 are rejected with 400. Keep the same `page_size` on every page of one search so pages neither overlap nor skip results.", "minimum": 1, "maximum": 50, "default": 20 }, "required": false, "description": "**Results per page.** Optional; defaults to `20`, accepts 1–50.\n\nValues above 50 are rejected with 400. Keep the same `page_size` on every page of one search so pages neither overlap nor skip results.", "name": "page_size", "in": "query" } ], "responses": { "200": { "description": "**The tags an author writes under** (makes, body types, topics), as `items: [{id, name}]`, optionally narrowed by a name fragment.\n\n- Pass a tag `id` to `/tag-news` to list every article carrying that tag, from any author.\n- Broad-coverage authors such as the editorial team carry the largest tag lists.\n- An unknown `author_id` returns 404.\n- `pagination.total_pages` is the page count at your `page_size`; `pagination.total_items` is not available on this list (`null`). A `page` past `total_pages` returns an empty `items` list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MotorySuccessResponseSchema" }, "example": { "success": true, "data": { "items": [ { "id": 78, "name": "Mazda" } ], "pagination": { "page": 1, "page_size": 20, "total_items": null, "total_pages": 8 } } } } } }, "400": { "description": "Bad request — a parameter is missing, malformed or out of range", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MotoryErrorResponseSchema" } } } }, "404": { "description": "Not found — the requested id or link does not exist", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MotoryErrorResponseSchema" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MotoryErrorResponseSchema" } } } }, "503": { "description": "Service busy — retry shortly", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MotoryErrorResponseSchema" } } } } } } }, "/tag-news": { "get": { "tags": [ "News" ], "operationId": "getNewsByTag", "description": "List the news articles carrying one tag, a topic such as SUV or a make such as Toyota, newest, oldest or most-read first, optionally narrowed to one category, one author or a title text. Takes a tag_id from /author-tags or an article's tags; open a row's id in /news-details.", "parameters": [ { "schema": { "type": "integer", "description": "**News tag id.** Required; for example `78` (Mazda in `sa`).\n\nTake `id` from `/author-tags`, or from `tags` on `/news-details` or `/author-details`, all called with the same `country`.\n\nA make id from `/makes` (same `country`) is also a tag id: it lists news about that make.\n\nWhen the list is empty:\n\n- A make id from `/makes` (`condition=used` or `new`) with no matching articles returns 200 with an empty list.\n\n- Any other id, without filters, returns 200 with an empty list when the tag has articles in the other language only, and 404 when it has articles in neither language.\n\n- Any other id, with `category_id`, `author_id` or `keyword`, returns 200 with an empty list when the tag has articles in this language without the filters. Otherwise it returns 404, and the message names where tag ids come from and notes that the tag may have articles only in the other `lang`.", "minimum": 1, "example": 78 }, "required": true, "description": "**News tag id.** Required; for example `78` (Mazda in `sa`).\n\nTake `id` from `/author-tags`, or from `tags` on `/news-details` or `/author-details`, all called with the same `country`.\n\nA make id from `/makes` (same `country`) is also a tag id: it lists news about that make.\n\nWhen the list is empty:\n\n- A make id from `/makes` (`condition=used` or `new`) with no matching articles returns 200 with an empty list.\n\n- Any other id, without filters, returns 200 with an empty list when the tag has articles in the other language only, and 404 when it has articles in neither language.\n\n- Any other id, with `category_id`, `author_id` or `keyword`, returns 200 with an empty list when the tag has articles in this language without the filters. Otherwise it returns 404, and the message names where tag ids come from and notes that the tag may have articles only in the other `lang`.", "name": "tag_id", "in": "query" }, { "schema": { "type": "integer", "description": "**Only articles in this news category.** Optional; one category id.\n\nTake `id` from `/news-categories` called with the same `country`; omit for all categories (the `-1` \"Home\" entry there is not a filter value and is rejected with 400). An id that is not a news category of the selected market is rejected with 400.", "minimum": 1 }, "required": false, "description": "**Only articles in this news category.** Optional; one category id.\n\nTake `id` from `/news-categories` called with the same `country`; omit for all categories (the `-1` \"Home\" entry there is not a filter value and is rejected with 400). An id that is not a news category of the selected market is rejected with 400.", "name": "category_id", "in": "query" }, { "schema": { "type": "integer", "description": "**Only articles by this author.** Optional; one author id.\n\nTake `author.id` from any article row fetched with the same `country`. An id that is not a news author of the selected market is rejected with 400.\n\nOn this route an unknown author is rejected with 400 only when `tag_id` is a make id from `/makes`. With any other `tag_id`, an unknown author returns an empty list.", "minimum": 1 }, "required": false, "description": "**Only articles by this author.** Optional; one author id.\n\nTake `author.id` from any article row fetched with the same `country`. An id that is not a news author of the selected market is rejected with 400.\n\nOn this route an unknown author is rejected with 400 only when `tag_id` is a make id from `/makes`. With any other `tag_id`, an unknown author returns an empty list.", "name": "author_id", "in": "query" }, { "schema": { "type": "string", "description": "**Only articles whose title contains this text**, case-insensitive. Optional; for example `toyota`.\n\nWrite Arabic text with `lang=ar` and English text with `lang=en`. No match returns an empty list.", "maxLength": 100 }, "required": false, "description": "**Only articles whose title contains this text**, case-insensitive. Optional; for example `toyota`.\n\nWrite Arabic text with `lang=ar` and English text with `lang=en`. No match returns an empty list.", "name": "keyword", "in": "query" }, { "schema": { "type": "string", "description": "**Article order.** Optional; defaults to `newest`.\n\n- `newest` — most recently published first\n- `oldest` — earliest published first\n- `most_read` — most-read articles first\n\nEvery filter applies under every order. `most_read` is the order of `/author-news` with `order_by=most_read`: an author's articles narrowed here with `author_id` come in the same order there, except that neighbouring articles can swap places.", "enum": [ "newest", "oldest", "most_read" ], "default": "newest" }, "required": false, "description": "**Article order.** Optional; defaults to `newest`.\n\n- `newest` — most recently published first\n- `oldest` — earliest published first\n- `most_read` — most-read articles first\n\nEvery filter applies under every order. `most_read` is the order of `/author-news` with `order_by=most_read`: an author's articles narrowed here with `author_id` come in the same order there, except that neighbouring articles can swap places.", "name": "sort", "in": "query" }, { "schema": { "type": "string", "description": "**Market to read.** Optional; defaults to `sa`.\n\n- `sa` — Saudi Arabia (prices in SAR)\n- `jo` — Jordan (prices in JOD)\n\nEach market has its own inventory and its own ids (makes, models, cities, body types, dealers, vehicles). Send only ids from a call made with the same `country`. An id from the other market is answered as an unknown id:\n\n- **404** — a lookup by id: every details route, `/models`, `/finance-providers`, and `category_id` on `/category-news` and `/videos`.\n- **400 naming the param** — `make_id`, `model_id` and `finance_provider_id` on `/new-cars` and `/new-car-filters`; `make_id` and `city_id` on `/dealers`; `make_id` and `company_id` on `/offers`; `make_id`, `author_id` and `category_id` as filters of the news lists, and `make_id` on `/videos` (on `/tag-news`, an unknown `author_id` with a tag that is not a make returns an empty list when the tag has articles in the requested `lang`, and 404 otherwise).\n- **Empty result** — every other id filter, for example `body_type_id`, `fuel_type_id`, `transmission_id` or `origin_id` on `/new-cars`, every `/used-cars` and `/used-car-filters` filter, and `dealer_id` on `/dealers`.", "enum": [ "sa", "jo" ], "default": "sa" }, "required": false, "description": "**Market to read.** Optional; defaults to `sa`.\n\n- `sa` — Saudi Arabia (prices in SAR)\n- `jo` — Jordan (prices in JOD)\n\nEach market has its own inventory and its own ids (makes, models, cities, body types, dealers, vehicles). Send only ids from a call made with the same `country`. An id from the other market is answered as an unknown id:\n\n- **404** — a lookup by id: every details route, `/models`, `/finance-providers`, and `category_id` on `/category-news` and `/videos`.\n- **400 naming the param** — `make_id`, `model_id` and `finance_provider_id` on `/new-cars` and `/new-car-filters`; `make_id` and `city_id` on `/dealers`; `make_id` and `company_id` on `/offers`; `make_id`, `author_id` and `category_id` as filters of the news lists, and `make_id` on `/videos` (on `/tag-news`, an unknown `author_id` with a tag that is not a make returns an empty list when the tag has articles in the requested `lang`, and 404 otherwise).\n- **Empty result** — every other id filter, for example `body_type_id`, `fuel_type_id`, `transmission_id` or `origin_id` on `/new-cars`, every `/used-cars` and `/used-car-filters` filter, and `dealer_id` on `/dealers`.", "name": "country", "in": "query" }, { "schema": { "type": "string", "description": "**Language of the news — and which articles you get.** Optional; defaults to `en`.\n\n- `en` — English\n- `ar` — Arabic\n\nNews is written separately in each language:\n\n- Each language has its own set of articles, and some articles and categories exist in one language only.\n- Ids are the same in both languages, but a list can hold different articles in each.\n- An article published in one language only returns 404 in the other; the message names the `lang` to use.", "enum": [ "en", "ar" ], "default": "en" }, "required": false, "description": "**Language of the news — and which articles you get.** Optional; defaults to `en`.\n\n- `en` — English\n- `ar` — Arabic\n\nNews is written separately in each language:\n\n- Each language has its own set of articles, and some articles and categories exist in one language only.\n- Ids are the same in both languages, but a list can hold different articles in each.\n- An article published in one language only returns 404 in the other; the message names the `lang` to use.", "name": "lang", "in": "query" }, { "schema": { "type": "integer", "description": "**Page number, starting at 1.** Optional; defaults to `1`.\n\nKeep `page_size` fixed while paging and stop at `pagination.total_pages`. A `page` beyond the last page returns an empty `items` list.", "minimum": 1, "maximum": 10000, "default": 1 }, "required": false, "description": "**Page number, starting at 1.** Optional; defaults to `1`.\n\nKeep `page_size` fixed while paging and stop at `pagination.total_pages`. A `page` beyond the last page returns an empty `items` list.", "name": "page", "in": "query" }, { "schema": { "type": "integer", "description": "**Results per page.** Optional; defaults to `20`, accepts 1–50.\n\nValues above 50 are rejected with 400. Keep the same `page_size` on every page of one search so pages neither overlap nor skip results.", "minimum": 1, "maximum": 50, "default": 20 }, "required": false, "description": "**Results per page.** Optional; defaults to `20`, accepts 1–50.\n\nValues above 50 are rejected with 400. Keep the same `page_size` on every page of one search so pages neither overlap nor skip results.", "name": "page_size", "in": "query" } ], "responses": { "200": { "description": "**The news articles carrying one tag**: a topic (SUV, Electric Vehicles, Car Tips…) or a make (news about Toyota, Mazda…). Newest first by default (or oldest or most-read first), optionally narrowed to one category, one author or a title text. Filters combine: every one must match.\n\nEach row in `items` is an article card as served:\n\n- `id` — the `news_id`; read the article in full with `/news-details`\n- `title`, `image` and `url` (the public article page)\n- `date` — `DD/MM/YYYY`\n- `category` — `{id, name}`\n- `author` — `{id, name, image}`; pass `author.id` to `/author-news`\n- `is_saved` — always `false` without a signed-in user\n- `short_body` — the excerpt; may contain HTML entities\n\nPaging, languages and empty results:\n\n- `pagination.total_pages` is the page count at your `page_size`; `pagination.total_items` is not available on this list (`null`). A `page` past `total_pages` returns an empty `items` list.\n- Each language has its own set of articles, so the same `tag_id` can list different articles with `lang=en` and `lang=ar`.\n- An empty result is a 200 or a 404 by the rules under `tag_id`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MotorySuccessResponseSchema" }, "example": { "success": true, "data": { "items": [ { "id": 12016, "title": "Mazda CX-9 2023...Thinking outside the box", "date": "28/02/2023", "category": { "id": 2427, "name": "Car Reports" }, "author": { "id": 3, "name": "Motory Editorial", "image": "https://s3.eu-central-1.amazonaws.com/v3-news.motory.com/news-author/l-1619350234.7454-608552dab5f8e.webp" }, "image": "https://s3.eu-central-1.amazonaws.com/v3-news.motory.com/news/l-1677420287.5671-63fb66ff8a757.webp", "is_saved": false, "url": "https://ksa.motory.com/en/news/mazda-cx-9-2023thinking-outside-the-box-12016/", "short_body": "The 2023 Mazda CX9 performance and design work together to create a stylish and attractive version of the SUV. The pleasurable sportiness of the drive..." } ], "pagination": { "page": 1, "page_size": 20, "total_items": null, "total_pages": 2 } } } } } }, "400": { "description": "Bad request — a parameter is missing, malformed or out of range", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MotoryErrorResponseSchema" } } } }, "404": { "description": "Not found — the requested id or link does not exist", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MotoryErrorResponseSchema" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MotoryErrorResponseSchema" } } } }, "503": { "description": "Service busy — retry shortly", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MotoryErrorResponseSchema" } } } } } } }, "/most-read-news": { "get": { "tags": [ "News" ], "operationId": "listMostReadNews", "description": "List the market's most-read news articles as a short list of article cards. Takes only country and lang; open a row's id in /news-details, or use /author-news with order_by=most_read for one author.", "parameters": [ { "schema": { "type": "string", "description": "**Market to read.** Optional; defaults to `sa`.\n\n- `sa` — Saudi Arabia (prices in SAR)\n- `jo` — Jordan (prices in JOD)\n\nEach market has its own inventory and its own ids (makes, models, cities, body types, dealers, vehicles). Send only ids from a call made with the same `country`. An id from the other market is answered as an unknown id:\n\n- **404** — a lookup by id: every details route, `/models`, `/finance-providers`, and `category_id` on `/category-news` and `/videos`.\n- **400 naming the param** — `make_id`, `model_id` and `finance_provider_id` on `/new-cars` and `/new-car-filters`; `make_id` and `city_id` on `/dealers`; `make_id` and `company_id` on `/offers`; `make_id`, `author_id` and `category_id` as filters of the news lists, and `make_id` on `/videos` (on `/tag-news`, an unknown `author_id` with a tag that is not a make returns an empty list when the tag has articles in the requested `lang`, and 404 otherwise).\n- **Empty result** — every other id filter, for example `body_type_id`, `fuel_type_id`, `transmission_id` or `origin_id` on `/new-cars`, every `/used-cars` and `/used-car-filters` filter, and `dealer_id` on `/dealers`.", "enum": [ "sa", "jo" ], "default": "sa" }, "required": false, "description": "**Market to read.** Optional; defaults to `sa`.\n\n- `sa` — Saudi Arabia (prices in SAR)\n- `jo` — Jordan (prices in JOD)\n\nEach market has its own inventory and its own ids (makes, models, cities, body types, dealers, vehicles). Send only ids from a call made with the same `country`. An id from the other market is answered as an unknown id:\n\n- **404** — a lookup by id: every details route, `/models`, `/finance-providers`, and `category_id` on `/category-news` and `/videos`.\n- **400 naming the param** — `make_id`, `model_id` and `finance_provider_id` on `/new-cars` and `/new-car-filters`; `make_id` and `city_id` on `/dealers`; `make_id` and `company_id` on `/offers`; `make_id`, `author_id` and `category_id` as filters of the news lists, and `make_id` on `/videos` (on `/tag-news`, an unknown `author_id` with a tag that is not a make returns an empty list when the tag has articles in the requested `lang`, and 404 otherwise).\n- **Empty result** — every other id filter, for example `body_type_id`, `fuel_type_id`, `transmission_id` or `origin_id` on `/new-cars`, every `/used-cars` and `/used-car-filters` filter, and `dealer_id` on `/dealers`.", "name": "country", "in": "query" }, { "schema": { "type": "string", "description": "**Language of the news — and which articles you get.** Optional; defaults to `en`.\n\n- `en` — English\n- `ar` — Arabic\n\nNews is written separately in each language:\n\n- Each language has its own set of articles, and some articles and categories exist in one language only.\n- Ids are the same in both languages, but a list can hold different articles in each.\n- An article published in one language only returns 404 in the other; the message names the `lang` to use.", "enum": [ "en", "ar" ], "default": "en" }, "required": false, "description": "**Language of the news — and which articles you get.** Optional; defaults to `en`.\n\n- `en` — English\n- `ar` — Arabic\n\nNews is written separately in each language:\n\n- Each language has its own set of articles, and some articles and categories exist in one language only.\n- Ids are the same in both languages, but a list can hold different articles in each.\n- An article published in one language only returns 404 in the other; the message names the `lang` to use.", "name": "lang", "in": "query" } ], "responses": { "200": { "description": "**The market's most-read news articles**, as `items` (a short list, not paged).\n\nEach row in `items` is an article card as served:\n\n- `id` — the `news_id`; read the article in full with `/news-details`\n- `title`, `image` and `url` (the public article page)\n- `date` — `DD/MM/YYYY`\n- `category` — `{id, name}`\n- `author` — `{id, name, image}`; pass `author.id` to `/author-news`\n- `is_saved` — always `false` without a signed-in user\n- `short_body` — the excerpt; may contain HTML entities\n\nFor one author's most-read articles use `/author-news` with `order_by=most_read`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MotorySuccessResponseSchema" }, "example": { "success": true, "data": { "items": [ { "id": 7025, "title": "Car Dash Warning Lights Meanings by Color and Level of Risk", "date": "20/01/2024", "category": { "id": 617, "name": "Car Advice" }, "author": { "id": 14, "name": "Zaina Al Natour", "image": "https://s3.eu-central-1.amazonaws.com/v3-news.motory.com/news-author/l-1625993452.0779-60eab0ec13073.webp" }, "image": "https://s3.eu-central-1.amazonaws.com/v3-news.motory.com/news/l-1708603491.7658-65d73863baf65.webp", "is_saved": false, "url": "https://ksa.motory.com/en/news/car-dash-warning-light-meaning/", "short_body": "The car’s dashboard, also known as the “instrument panel,” serves as a unique unspoken language between the vehicle and its driver. It sends instant s..." } ] } } } } }, "400": { "description": "Bad request — a parameter is missing, malformed or out of range", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MotoryErrorResponseSchema" } } } }, "404": { "description": "Not found — the requested id or link does not exist", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MotoryErrorResponseSchema" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MotoryErrorResponseSchema" } } } }, "503": { "description": "Service busy — retry shortly", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MotoryErrorResponseSchema" } } } } } } }, "/video-categories": { "get": { "tags": [ "Videos" ], "operationId": "listVideoCategories", "description": "List the video categories of a market (Reviews, Motory Studio, One Minute Brief, Electric Cars). Takes only country and lang; pass a category id as category_id to /videos.", "parameters": [ { "schema": { "type": "string", "description": "**Market to read.** Optional; defaults to `sa`.\n\n- `sa` — Saudi Arabia (prices in SAR)\n- `jo` — Jordan (prices in JOD)\n\nEach market has its own inventory and its own ids (makes, models, cities, body types, dealers, vehicles). Send only ids from a call made with the same `country`. An id from the other market is answered as an unknown id:\n\n- **404** — a lookup by id: every details route, `/models`, `/finance-providers`, and `category_id` on `/category-news` and `/videos`.\n- **400 naming the param** — `make_id`, `model_id` and `finance_provider_id` on `/new-cars` and `/new-car-filters`; `make_id` and `city_id` on `/dealers`; `make_id` and `company_id` on `/offers`; `make_id`, `author_id` and `category_id` as filters of the news lists, and `make_id` on `/videos` (on `/tag-news`, an unknown `author_id` with a tag that is not a make returns an empty list when the tag has articles in the requested `lang`, and 404 otherwise).\n- **Empty result** — every other id filter, for example `body_type_id`, `fuel_type_id`, `transmission_id` or `origin_id` on `/new-cars`, every `/used-cars` and `/used-car-filters` filter, and `dealer_id` on `/dealers`.", "enum": [ "sa", "jo" ], "default": "sa" }, "required": false, "description": "**Market to read.** Optional; defaults to `sa`.\n\n- `sa` — Saudi Arabia (prices in SAR)\n- `jo` — Jordan (prices in JOD)\n\nEach market has its own inventory and its own ids (makes, models, cities, body types, dealers, vehicles). Send only ids from a call made with the same `country`. An id from the other market is answered as an unknown id:\n\n- **404** — a lookup by id: every details route, `/models`, `/finance-providers`, and `category_id` on `/category-news` and `/videos`.\n- **400 naming the param** — `make_id`, `model_id` and `finance_provider_id` on `/new-cars` and `/new-car-filters`; `make_id` and `city_id` on `/dealers`; `make_id` and `company_id` on `/offers`; `make_id`, `author_id` and `category_id` as filters of the news lists, and `make_id` on `/videos` (on `/tag-news`, an unknown `author_id` with a tag that is not a make returns an empty list when the tag has articles in the requested `lang`, and 404 otherwise).\n- **Empty result** — every other id filter, for example `body_type_id`, `fuel_type_id`, `transmission_id` or `origin_id` on `/new-cars`, every `/used-cars` and `/used-car-filters` filter, and `dealer_id` on `/dealers`.", "name": "country", "in": "query" }, { "schema": { "type": "string", "description": "**Response language.** Optional; defaults to `en`.\n\n- `en` — English\n- `ar` — Arabic\n\nChanges labels, titles and descriptions only; ids and numeric values are the same in both languages.", "enum": [ "en", "ar" ], "default": "en" }, "required": false, "description": "**Response language.** Optional; defaults to `en`.\n\n- `en` — English\n- `ar` — Arabic\n\nChanges labels, titles and descriptions only; ids and numeric values are the same in both languages.", "name": "lang", "in": "query" } ], "responses": { "200": { "description": "**The video categories of one market**, as `items: [{id, name}]` (Reviews, Motory Studio, One Minute Brief, Electric Cars…).\n\n- Pass an `id` as `category_id` to `/videos`.\n- The `-1` entry (\"All Videos\") is the \"All\" entry: it stands for every category and is not a filter value. Omit `category_id` on `/videos` to get all videos; `category_id=-1` is rejected with 400.\n- Category ids differ between markets, and each market has its own set.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MotorySuccessResponseSchema" }, "example": { "success": true, "data": { "items": [ { "id": -1, "name": "All Videos" } ] } } } } }, "400": { "description": "Bad request — a parameter is missing, malformed or out of range", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MotoryErrorResponseSchema" } } } }, "404": { "description": "Not found — the requested id or link does not exist", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MotoryErrorResponseSchema" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MotoryErrorResponseSchema" } } } }, "503": { "description": "Service busy — retry shortly", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MotoryErrorResponseSchema" } } } } } } }, "/videos": { "get": { "tags": [ "Videos" ], "operationId": "listVideos", "description": "List the marketplace's car videos, newest or oldest first, optionally for one category, make, model or model year; with no filter the featured videos come in a list of their own. Take ids from /video-categories, /makes and /models; open a video id in /video-details.", "parameters": [ { "schema": { "type": "integer", "description": "**Video category.** Optional; one category id.\n\nTake `id` from `/video-categories` called with the same `country`; omit for all videos (the `-1` \"All Videos\" entry there is not a filter value and is rejected with 400). One value only — a comma-separated list is rejected with 400. An unknown id returns 404.", "minimum": 1 }, "required": false, "description": "**Video category.** Optional; one category id.\n\nTake `id` from `/video-categories` called with the same `country`; omit for all videos (the `-1` \"All Videos\" entry there is not a filter value and is rejected with 400). One value only — a comma-separated list is rejected with 400. An unknown id returns 404.", "name": "category_id", "in": "query" }, { "schema": { "type": "integer", "description": "**Videos about one make.** Optional; one make id (for example `90`).\n\nTake ids from `filter_lists.makes_list` of this endpoint (makes that have videos) or from `/makes`, called with the same `country`. Combines with the other filters (all must match). One value only. A make without videos returns an empty list; an id that is in neither `/makes` list (`condition=used` or `new`) of the selected market is rejected with 400.", "minimum": 1 }, "required": false, "description": "**Videos about one make.** Optional; one make id (for example `90`).\n\nTake ids from `filter_lists.makes_list` of this endpoint (makes that have videos) or from `/makes`, called with the same `country`. Combines with the other filters (all must match). One value only. A make without videos returns an empty list; an id that is in neither `/makes` list (`condition=used` or `new`) of the selected market is rejected with 400.", "name": "make_id", "in": "query" }, { "schema": { "type": "integer", "description": "**Videos about one model.** Optional; one model id.\n\nTake ids from `/models` called with the same `country`. Works without `make_id`; combined with a `make_id` the model does not belong to, the list is empty. One value only. A model without videos — or an id unknown to the market — returns an empty list.\n\nWithout `make_id` or `category_id`, featured videos of this model are not in `items` and `featured_videos` is empty: send the model's `make_id` as well to get them in `items`.", "minimum": 1 }, "required": false, "description": "**Videos about one model.** Optional; one model id.\n\nTake ids from `/models` called with the same `country`. Works without `make_id`; combined with a `make_id` the model does not belong to, the list is empty. One value only. A model without videos — or an id unknown to the market — returns an empty list.\n\nWithout `make_id` or `category_id`, featured videos of this model are not in `items` and `featured_videos` is empty: send the model's `make_id` as well to get them in `items`.", "name": "model_id", "in": "query" }, { "schema": { "type": "integer", "description": "**Videos about cars of this model year.** Optional; one year.\n\nThe model year of the car in the video (a review of a 2024 car), not the date the video was added. A year without videos returns an empty list.\n\nWithout `make_id` or `category_id`, featured videos of this year are not in `items` and `featured_videos` is empty: send a `make_id` as well to get that make's matching featured videos in `items`.", "minimum": 1900, "maximum": 2100 }, "required": false, "description": "**Videos about cars of this model year.** Optional; one year.\n\nThe model year of the car in the video (a review of a 2024 car), not the date the video was added. A year without videos returns an empty list.\n\nWithout `make_id` or `category_id`, featured videos of this year are not in `items` and `featured_videos` is empty: send a `make_id` as well to get that make's matching featured videos in `items`.", "name": "year", "in": "query" }, { "schema": { "type": "string", "description": "**Order by when the video was added.** Optional; defaults to `newest`.\n\n- `newest` — latest added first\n- `oldest` — earliest added first\n\nThe order follows when each video was added to the catalogue (its `id`), not the `created_at` date shown on a row, so neighbouring rows can show dates several weeks out of order.", "enum": [ "newest", "oldest" ], "default": "newest" }, "required": false, "description": "**Order by when the video was added.** Optional; defaults to `newest`.\n\n- `newest` — latest added first\n- `oldest` — earliest added first\n\nThe order follows when each video was added to the catalogue (its `id`), not the `created_at` date shown on a row, so neighbouring rows can show dates several weeks out of order.", "name": "sort", "in": "query" }, { "schema": { "type": "string", "description": "**Market to read.** Optional; defaults to `sa`.\n\n- `sa` — Saudi Arabia (prices in SAR)\n- `jo` — Jordan (prices in JOD)\n\nEach market has its own inventory and its own ids (makes, models, cities, body types, dealers, vehicles). Send only ids from a call made with the same `country`. An id from the other market is answered as an unknown id:\n\n- **404** — a lookup by id: every details route, `/models`, `/finance-providers`, and `category_id` on `/category-news` and `/videos`.\n- **400 naming the param** — `make_id`, `model_id` and `finance_provider_id` on `/new-cars` and `/new-car-filters`; `make_id` and `city_id` on `/dealers`; `make_id` and `company_id` on `/offers`; `make_id`, `author_id` and `category_id` as filters of the news lists, and `make_id` on `/videos` (on `/tag-news`, an unknown `author_id` with a tag that is not a make returns an empty list when the tag has articles in the requested `lang`, and 404 otherwise).\n- **Empty result** — every other id filter, for example `body_type_id`, `fuel_type_id`, `transmission_id` or `origin_id` on `/new-cars`, every `/used-cars` and `/used-car-filters` filter, and `dealer_id` on `/dealers`.", "enum": [ "sa", "jo" ], "default": "sa" }, "required": false, "description": "**Market to read.** Optional; defaults to `sa`.\n\n- `sa` — Saudi Arabia (prices in SAR)\n- `jo` — Jordan (prices in JOD)\n\nEach market has its own inventory and its own ids (makes, models, cities, body types, dealers, vehicles). Send only ids from a call made with the same `country`. An id from the other market is answered as an unknown id:\n\n- **404** — a lookup by id: every details route, `/models`, `/finance-providers`, and `category_id` on `/category-news` and `/videos`.\n- **400 naming the param** — `make_id`, `model_id` and `finance_provider_id` on `/new-cars` and `/new-car-filters`; `make_id` and `city_id` on `/dealers`; `make_id` and `company_id` on `/offers`; `make_id`, `author_id` and `category_id` as filters of the news lists, and `make_id` on `/videos` (on `/tag-news`, an unknown `author_id` with a tag that is not a make returns an empty list when the tag has articles in the requested `lang`, and 404 otherwise).\n- **Empty result** — every other id filter, for example `body_type_id`, `fuel_type_id`, `transmission_id` or `origin_id` on `/new-cars`, every `/used-cars` and `/used-car-filters` filter, and `dealer_id` on `/dealers`.", "name": "country", "in": "query" }, { "schema": { "type": "string", "description": "**Response language.** Optional; defaults to `en`.\n\n- `en` — English\n- `ar` — Arabic\n\nChanges labels, titles and descriptions only; ids and numeric values are the same in both languages.", "enum": [ "en", "ar" ], "default": "en" }, "required": false, "description": "**Response language.** Optional; defaults to `en`.\n\n- `en` — English\n- `ar` — Arabic\n\nChanges labels, titles and descriptions only; ids and numeric values are the same in both languages.", "name": "lang", "in": "query" }, { "schema": { "type": "integer", "description": "**Page number, starting at 1.** Optional; defaults to `1`.\n\nKeep `page_size` fixed while paging and stop at `pagination.total_pages`. A `page` beyond the last page returns an empty `items` list.", "minimum": 1, "maximum": 10000, "default": 1 }, "required": false, "description": "**Page number, starting at 1.** Optional; defaults to `1`.\n\nKeep `page_size` fixed while paging and stop at `pagination.total_pages`. A `page` beyond the last page returns an empty `items` list.", "name": "page", "in": "query" }, { "schema": { "type": "integer", "description": "**Results per page.** Optional; defaults to `20`, accepts 1–50.\n\nValues above 50 are rejected with 400. Keep the same `page_size` on every page of one search so pages neither overlap nor skip results.", "minimum": 1, "maximum": 50, "default": 20 }, "required": false, "description": "**Results per page.** Optional; defaults to `20`, accepts 1–50.\n\nValues above 50 are rejected with 400. Keep the same `page_size` on every page of one search so pages neither overlap nor skip results.", "name": "page_size", "in": "query" } ], "responses": { "200": { "description": "**The marketplace's car videos** (reviews, studio episodes, short briefs), newest or oldest first, optionally narrowed by category, make, model and car model year. Filters combine: every one must match.\n\nEach row in `items` is served as-is:\n\n- `id` — the `video_id`; read the video, including its playable `link`, with `/video-details`\n- `title` and `thumbnail`\n- `category` — the category name\n- `created_at` — `DD/MM/YYYY`\n\n`featured_videos` has the same row shape and is on every page:\n\n- With no filter, it holds the featured videos as served, and `items` leaves them out: read both lists. A video is never in both lists.\n- With any filter (`category_id`, `make_id`, `model_id` or `year`), it is an empty list.\n- With `make_id` or `category_id`, the featured videos that match are already in `items`.\n- With only `model_id` and/or `year`, the featured videos are not in `items`. Send the model's `make_id` as well to get the matching featured videos in `items`.\n\nOther fields and paging:\n\n- `filter_lists.makes_list` (`{id, name, logo}`) lists the makes that have videos — within the selected category when `category_id` is sent — and is the vocabulary of `make_id`.\n- `pagination.total_pages` is the page count at your `page_size`; `pagination.total_items` is not available on this list (`null`). A `page` past `total_pages` returns an empty `items` list. The page count covers `items` only, not `featured_videos`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MotorySuccessResponseSchema" }, "example": { "success": true, "data": { "items": [ { "id": 1476, "title": "Jetour G700 Full Review!", "thumbnail": "https://cdn.jwplayer.com/v2/media/FHqP8i4i/poster.jpg?width=640", "category": "Reviews", "created_at": "30/08/2026" } ], "featured_videos": [ { "id": 1541, "title": "A Comprehensive Look at MG RX9 2026 Specifications!", "thumbnail": "https://cdn.jwplayer.com/v2/media/MX5qysQm/poster.jpg?width=640", "category": "Reviews", "created_at": "07/10/2026" } ], "filter_lists": { "makes_list": [ { "id": 45, "name": "Ford", "logo": "https://s3.eu-central-1.amazonaws.com/v3-common.motory.com/taxonomy/139x139/l-1669882628.5401-6388630483dfe.webp" } ] }, "pagination": { "page": 1, "page_size": 20, "total_items": null, "total_pages": 17 } } } } } }, "400": { "description": "Bad request — a parameter is missing, malformed or out of range", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MotoryErrorResponseSchema" } } } }, "404": { "description": "Not found — the requested id or link does not exist", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MotoryErrorResponseSchema" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MotoryErrorResponseSchema" } } } }, "503": { "description": "Service busy — retry shortly", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MotoryErrorResponseSchema" } } } } } } }, "/video-details": { "get": { "tags": [ "Videos" ], "operationId": "getVideoDetails", "description": "Read one video: playable MP4 link, description, category and related videos, news, new cars and offers. Takes a video_id from a /videos row (items or featured_videos).", "parameters": [ { "schema": { "type": "integer", "description": "**Video id.** Required; for example `1476` (in `sa`).\n\nTake `id` from `/videos` (`items` or `featured_videos`), or from `related.videos` here, fetched with the same `country`. Video ids differ between markets; an unknown id returns 404.", "minimum": 1, "example": 1476 }, "required": true, "description": "**Video id.** Required; for example `1476` (in `sa`).\n\nTake `id` from `/videos` (`items` or `featured_videos`), or from `related.videos` here, fetched with the same `country`. Video ids differ between markets; an unknown id returns 404.", "name": "video_id", "in": "query" }, { "schema": { "type": "string", "description": "**Market to read.** Optional; defaults to `sa`.\n\n- `sa` — Saudi Arabia (prices in SAR)\n- `jo` — Jordan (prices in JOD)\n\nEach market has its own inventory and its own ids (makes, models, cities, body types, dealers, vehicles). Send only ids from a call made with the same `country`. An id from the other market is answered as an unknown id:\n\n- **404** — a lookup by id: every details route, `/models`, `/finance-providers`, and `category_id` on `/category-news` and `/videos`.\n- **400 naming the param** — `make_id`, `model_id` and `finance_provider_id` on `/new-cars` and `/new-car-filters`; `make_id` and `city_id` on `/dealers`; `make_id` and `company_id` on `/offers`; `make_id`, `author_id` and `category_id` as filters of the news lists, and `make_id` on `/videos` (on `/tag-news`, an unknown `author_id` with a tag that is not a make returns an empty list when the tag has articles in the requested `lang`, and 404 otherwise).\n- **Empty result** — every other id filter, for example `body_type_id`, `fuel_type_id`, `transmission_id` or `origin_id` on `/new-cars`, every `/used-cars` and `/used-car-filters` filter, and `dealer_id` on `/dealers`.", "enum": [ "sa", "jo" ], "default": "sa" }, "required": false, "description": "**Market to read.** Optional; defaults to `sa`.\n\n- `sa` — Saudi Arabia (prices in SAR)\n- `jo` — Jordan (prices in JOD)\n\nEach market has its own inventory and its own ids (makes, models, cities, body types, dealers, vehicles). Send only ids from a call made with the same `country`. An id from the other market is answered as an unknown id:\n\n- **404** — a lookup by id: every details route, `/models`, `/finance-providers`, and `category_id` on `/category-news` and `/videos`.\n- **400 naming the param** — `make_id`, `model_id` and `finance_provider_id` on `/new-cars` and `/new-car-filters`; `make_id` and `city_id` on `/dealers`; `make_id` and `company_id` on `/offers`; `make_id`, `author_id` and `category_id` as filters of the news lists, and `make_id` on `/videos` (on `/tag-news`, an unknown `author_id` with a tag that is not a make returns an empty list when the tag has articles in the requested `lang`, and 404 otherwise).\n- **Empty result** — every other id filter, for example `body_type_id`, `fuel_type_id`, `transmission_id` or `origin_id` on `/new-cars`, every `/used-cars` and `/used-car-filters` filter, and `dealer_id` on `/dealers`.", "name": "country", "in": "query" }, { "schema": { "type": "string", "description": "**Response language.** Optional; defaults to `en`.\n\n- `en` — English\n- `ar` — Arabic\n\nChanges labels, titles and descriptions only; ids and numeric values are the same in both languages.", "enum": [ "en", "ar" ], "default": "en" }, "required": false, "description": "**Response language.** Optional; defaults to `en`.\n\n- `en` — English\n- `ar` — Arabic\n\nChanges labels, titles and descriptions only; ids and numeric values are the same in both languages.", "name": "lang", "in": "query" } ], "responses": { "200": { "description": "**One video**, as served:\n\n- `title`, `description` and `category`\n- `created_at` — `DD/MM/YYYY`\n- `video_type`, `link` (the playable MP4 file), `thumbnail` and `share_link` (the public page)\n- `related` — the blocks below\n\n`related` is served as-is, and its keys vary from video to video. Read the keys that are present; typical keys:\n\n- `videos` — more videos like this one\n- `related_news` — one article about the same make\n- `vehicles_new` — new cars of that make with prices\n- `car_offers` — current offers for that make\n- `suggestedVehiclesList` — the make's new cars; some videos carry it instead of `vehicles_new`\n\nEach block has its `section_title` and, where present, `section_link`. An unknown `video_id` returns 404.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MotorySuccessResponseSchema" }, "example": { "success": true, "data": { "id": 1476, "title": "Jetour G700 Full Review!", "description": "In this video, we take a comprehensive look at the Jetour G700 in the Saudi market, highlighting its key exterior and interior details, along with its performance and features.", "category": "Reviews", "created_at": "30/08/2026", "video_type": "jwplayer", "link": "https://cdn.jwplayer.com/videos/FHqP8i4i-46VPhlnS.mp4", "thumbnail": "https://cdn.jwplayer.com/v2/media/FHqP8i4i/poster.jpg?width=640", "related": { "videos": { "section_title": "You may also like", "data": [ { "id": 1083, "title": "Jetour G700 2025 Review", "thumbnail": "https://cdn.jwplayer.com/v2/media/YIW4iM4j/poster.jpg?width=640", "category": "Reviews", "created_at": "23/11/2025" } ] }, "related_news": { "section_title": "Jetour News", "section_link": "https://ksa.motory.com/en/news/jetour/", "data": { "id": 19264, "title": "Motory Team Explores Jetour G700 2026", "date": "31/08/2026", "category": { "id": 2427, "name": "Car Reports" }, "author": { "id": 12, "name": "Raghad Alqaryouti", "image": "https://s3.eu-central-1.amazonaws.com/v3-news.motory.com/news-author/l-1728471328.1472-6706612023eef_outbound.webp" }, "image": "https://s3.eu-central-1.amazonaws.com/v3-news.motory.com/news/l-1787834368.5795-6a9030008d7b4.webp", "is_saved": false, "url": "https://ksa.motory.com/en/news/jetour-g700-2026/", "short_body": "After a thorough review of the car, Motory team explores Jetour G700 2026 specifications in detail. This full size SUV is equipped with a plug in hybr..." } }, "vehicles_new": { "section_title": "Jetour New Cars", "section_link": "https://ksa.motory.com/en/new-cars/jetour/", "data": [ { "vehicle_id": 278226, "make_name": "Jetour", "make_id": 64, "model_name": "G700", "model_id": 8454, "grade": "Comfort", "title": "Jetour G700 Comfort 2026", "year": 2026, "price": 179990, "price_text": "Asking Price", "monthly_payment": null, "finance_available": true, "image": "https://s3.eu-central-1.amazonaws.com/v3-ncg.motory.com/vehicle-new/l-1782748447.2944-6a42951f47e21.webp", "icon": "https://s3.eu-central-1.amazonaws.com/v3-common.motory.com/taxonomy/l-1669879046.3947-63885506605ea.webp", "price_object": { "hide_price": false, "price_text": "Cash Price", "price_value": "179,990", "price_currency": "SR", "price_note": null, "monthly_payment": null, "down_payment": null, "final_payment": null, "total_amount": null, "period": null, "has_financing": true, "finance_text": "Financing", "finance_value": "Available", "disabled_finance_value": false, "disabled_price_value": false, "finance_currency": "", "percentage": null, "show_finance_button": true, "show_cash_button": true, "show_call_button": false } } ], "view_more": false }, "car_offers": { "section_title": "Jetour Offers", "section_link": "https://ksa.motory.com/en/cars-offers/", "data": [ { "id": 4798, "title": "Al Badr Cars — Your next car is closer than you think! 🚘🔥", "offer_begin": "05/10/2026", "offer_end": "31/10/2026", "image": "https://s3.eu-central-1.amazonaws.com/v3-car-offer.motory.com/car-offer/l-1791201049.4543-6ac38f196eea5.webp" } ] } }, "share_link": "https://ksa.motory.com/en/motory-videos/car-reviews/jetour-g700-full-review/" } } } } }, "400": { "description": "Bad request — a parameter is missing, malformed or out of range", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MotoryErrorResponseSchema" } } } }, "404": { "description": "Not found — the requested id or link does not exist", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MotoryErrorResponseSchema" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MotoryErrorResponseSchema" } } } }, "503": { "description": "Service busy — retry shortly", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MotoryErrorResponseSchema" } } } } } } } } }