داده‌های نمودا برای برنامه‌ها و پژوهش

همهٔ عددهای نمودا از نشانی‌های عمومی هم خوانده می‌شوند؛ رایگان، بی‌ثبت‌نام و بی‌کلید. این صفحه می‌گوید هر نشانی چه می‌دهد، بازار و ویژگی‌ها را چطور انتخاب کنید، هر عدد چه معنایی دارد و هنگام استفاده چطور نام نمودا را بیاورید.

نشانی‌ها

همهٔ نشانی‌ها با GET خوانده می‌شوند، بی‌ثبت‌نام و بی‌کلید، و پاسخشان JSON است. هر نشانی را می‌شود از مرورگر هم خواند، از هر سایتی. همه زیر این نشانی‌اند:

https://api.nemuda.com/api/market/
  • /api/market/meta — زمان آخرین محاسبه، طول پنجره به روز، بازارهایی که عدد دارند و ویژگی‌های هر کدام، و نرخی که ودیعه با آن به اجاره تبدیل می‌شود. methodVersion تاریخ روشی است که عددها با آن حساب می‌شوند و با عوض شدن روش عوض می‌شود؛ windowLadderDays روزهایی است که عدد هر بازار ممکن است از آن‌ها ساخته شود، و windowTargetPriced چند داده باید در ۱۴ روز گذشته باشد تا عدد فقط از همان روزها ساخته شود. برای هر بازار هم می‌گوید عدد اصلی‌اش برای چیست (priceBasis: هر متر، هر متر در ماه، یا هر شب) و قیمت‌هایش چطور سهم گرفته‌اند (weighting).
  • /api/market/real-estate/summary — کل ایران و همهٔ استان‌ها، در یک پاسخ.
  • /api/market/real-estate/places/{placeId}/children — شهرهای یک استان یا محله‌های یک شهر، گران‌ترین اول. جاهایی که عدد ندارند هم در آن هستند، با تعداد داده‌هایشان.
  • /api/market/real-estate/places/{placeId} — یک جا: عددش در این بازار، جای بالاتر از آن، و عددش در هر نوع ملک.
  • /api/market/real-estate/places/{placeId}/facets — برای یک جا و انتخاب فعلی: اگر یک ویژگی به گزینهٔ دیگری برود، عدد چه می‌شود و روی چند داده می‌ایستد.
  • /api/market/real-estate/place-index — همهٔ جاها با شناسه، نام و نشانی، و اینکه در این بازار عدد دارند یا نه؛ برای پیدا کردن placeId هر جا.
  • /api/market/real-estate/outlines — شهرهایی که محدودهٔ محله‌هایشان را داریم، با نسخهٔ هر کدام.
  • /api/market/real-estate/places/{placeId}/outlines — محدودهٔ محله‌های یک شهر به شکل TopoJSON، با طول و عرض جغرافیایی؛ همان که نقشهٔ شهر از آن کشیده می‌شود.

انتخاب بازار و ویژگی‌ها

بی‌پارامتر، هر نشانی دربارهٔ خرید آپارتمان است. بازار را با این دو پارامتر انتخاب کنید؛ زمین فقط خرید دارد، و اجارهٔ روزانه فقط سوئیت و آپارتمان، و ویلا دارد:

propertyKind=apartment|house|land|shop|office
dealType=sell|rent|stay
dealType=stay&propertyKind=apartment|house

در اجارهٔ روزانه، propertyKind=apartment سوئیت، آپارتمان، اتاق و اقامتگاه بوم‌گردی است و propertyKind=house ویلا. خوابگاه و پانسیون در هیچ‌کدام نیستند. در ویلا، pool=no یعنی میزبان برایش استخری ثبت نکرده است، نه اینکه گفته باشد ندارد.

هر بازار ویژگی‌های خودش را دارد و هر ویژگی یک پارامتر است. فهرست امروزشان این است؛ فهرست همیشه درست در propertyKinds[].facets در پاسخ /api/market/meta است:

propertyKind=apartment  area=lt60|60-80|80-100|100-150|gte150
propertyKind=apartment  rooms=1|2|3plus
propertyKind=apartment  age=new|mid|old
propertyKind=apartment  parking=yes|no
propertyKind=apartment  elevator=yes|no
propertyKind=house  area=lt100|100-150|150-250|gte250
propertyKind=house  land=lt150|150-300|300-500|gte500
propertyKind=house  age=new|mid|old
propertyKind=land  area=lt250|250-500|500-1000|1000-10000|gte10000
propertyKind=land  use=residential|garden|farm|commercial
propertyKind=shop  area=lt20|20-40|40-80|gte80
propertyKind=shop  ownership=full|goodwill
propertyKind=shop  location=street|mall|bazaar|alley
propertyKind=office  area=lt60|60-100|100-200|gte200
propertyKind=office  age=new|mid|old
propertyKind=office  parking=yes|no
dealType=rent&propertyKind=apartment  area=lt60|60-80|80-100|100-150|gte150
dealType=rent&propertyKind=apartment  rooms=1|2|3plus
dealType=rent&propertyKind=apartment  age=new|mid|old
dealType=rent&propertyKind=apartment  parking=yes|no
dealType=rent&propertyKind=apartment  elevator=yes|no
dealType=rent&propertyKind=house  area=lt100|100-150|150-250|gte250
dealType=rent&propertyKind=house  land=lt150|150-300|300-500|gte500
dealType=rent&propertyKind=house  age=new|mid|old
dealType=rent&propertyKind=shop  area=lt20|20-40|40-80|gte80
dealType=rent&propertyKind=shop  location=street|mall|bazaar|alley
dealType=rent&propertyKind=office  area=lt60|60-100|100-200|gte200
dealType=rent&propertyKind=office  age=new|mid|old
dealType=rent&propertyKind=office  parking=yes|no
dealType=stay&propertyKind=apartment  rooms=1|2|3plus
dealType=stay&propertyKind=house  rooms=1|2|3plus
dealType=stay&propertyKind=house  pool=yes|no

هر ویژگی را که نیاورید یعنی «فرقی نمی‌کند». بازاری که نباشد، ویژگی‌ای که آن بازار ندارد یا گزینه‌ای که آن ویژگی ندارد پاسخ 400 می‌گیرد، نه عدد بازار دیگری. هر پاسخ در filters می‌گوید عددش با کدام ویژگی‌ها ساخته شده است.

چند درخواست برای شروع

شناسهٔ شهر تهران 1 است. این‌ها عدد آن را در چند بازار می‌دهند:

https://api.nemuda.com/api/market/real-estate/places/1
https://api.nemuda.com/api/market/real-estate/places/1?propertyKind=shop
https://api.nemuda.com/api/market/real-estate/places/1?dealType=rent
https://api.nemuda.com/api/market/real-estate/places/1?dealType=stay
https://api.nemuda.com/api/market/real-estate/places/1/children?rooms=1&age=new
https://api.nemuda.com/api/market/real-estate/places/1/facets?dealType=rent&rooms=1&age=new

معنی هر عدد در پاسخ

  • pricePerM2 — عدد اصلی: قیمت وسط یک متر، به تومان. در اجاره، اجارهٔ ماهانهٔ یک متر با سهم ودیعه‌اش. در اجارهٔ روزانه null است؛ عدد اصلی آن pricePerNight است.
  • pricePerM2Range — نیمهٔ وسط قیمت‌ها: یک‌چهارم از low ارزان‌ترند و یک‌چهارم از high گران‌تر. کمترین و بیشترین قیمت نیست.
  • priceTotal و areaM2 — قیمت کل وسط و متراژ وسط. هر عدد جدا حساب شده، پس متراژ ضرب در قیمت هر متر دقیقاً قیمت کل نمی‌شود، و این فرق خطا نیست.
  • deposit و monthlyRent — فقط در اجاره: ودیعهٔ وسط و اجارهٔ ماهانهٔ وسط، هر کدام جدا؛ این دو با هم اجارهٔ یک ملک واقعی نیستند.
  • pricePerNight و pricePerNightRange — فقط در اجارهٔ روزانه: نرخ وسط یک شب وسط هفته برای اجارهٔ دربستی کل ملک، به تومان، نه برای هر متر و نه برای هر نفر؛ و نیمهٔ وسط همین نرخ‌ها.
  • weekendPricePerNight و holidayPricePerNight — فقط در اجارهٔ روزانه: وسط نرخ‌های آخر هفته و وسط نرخ‌های تعطیلات، هر کدام از میزبان‌هایی که آن نرخ را اعلام کرده‌اند؛ این سه با هم نرخ‌های یک ملک واقعی نیستند. جایی که کم اعلام شده، null است.
  • guests — فقط در اجارهٔ روزانه: یک ملک معمولی آنجا برای چند نفر است، به عدد صحیح.
  • heat — فقط در خرید: حال بازار، اینکه در دو هفتهٔ گذشته دست فروشنده‌ها بالاتر بوده یا خریدارها. level یکی از buyers، leaning-buyers، balanced، leaning-sellers و sellers است؛ position جای آن روی خطی از سر خریدار (صفر) تا سر فروشنده (صد)، همیشه در همان حالت، و evidence می‌گوید خوانش به دادهٔ خود آنجا تکیه دارد (solid) یا به حال کل کشور نزدیک است (thin). در اجاره، در عدد ساخته‌شده با ویژگی‌ها، در محله و جایی که بازارش آن‌قدر فعال نبوده، null است. معنی‌اش در روش و تعریف‌ها آمده است.
  • dataPoints — چند داده پشت عدد است، در روزهای windowDays همان عدد. هر داده یک قیمت، اجاره یا نرخ شب است که فروشنده، مالک یا میزبانی اعلام کرده. در عددی که با ویژگی‌ها ساخته شده و کمتر از ۱۰ داده دارد، null است.
  • coverage — none یعنی عددی منتشر نمی‌شود و همهٔ قیمت‌ها null است — معمولاً چون کمتر از ۱۰ داده دارد، ولی گاهی با ۱۰ داده یا بیشتر هم، وقتی قاعدهٔ انتشار عدد را نگه می‌دارد (dataPoints در این حالت عدد واقعی است)؛ limited یعنی عدد منتشر شده و ۱۰ تا ۲۹ داده پشت آن است؛ solid یعنی ۳۰ داده و بیشتر.
  • slug — بخشی از نشانی صفحهٔ آن جا. نشانی صفحه همیشه با حروف کوچک است، حتی اگر slug حرف بزرگ داشته باشد.
  • computedAt — زمان محاسبه، به وقت جهانی؛ asOf روزی که عدد دربارهٔ آن است؛ windowDays بالای هر پاسخ، پنجرهٔ پایه به روز.
  • windowDays در هر جا — عدد آن جا از قیمت‌های چند روز گذشته ساخته شده: ۱۴، و جایی که در ۱۴ روز کمتر از ۱۰۰ داده بوده بیشتر، تا ۴۲ روز (اجارهٔ روزانه وقتی کمتر از ۳۰ داده دارد، تا ۲۸ روز). عددی که با ویژگی‌ها ساخته شده روزهای همان جا را دارد. قیمتی که روزهای قبل اعلام شده، پیش از حساب به اندازهٔ تغییر قیمت آن بازار در کل ایران تا روز عدد بالا یا پایین برده شده است.

عدد یک شهر میانگین عدد محله‌هایش نیست: بخشی از قیمت‌ها فقط شهر را دارند، نه محله را. چیزی کوچک‌تر از یک محله هم منتشر نمی‌شود: نه ملک، نه نشانی، نه فروشنده.

قیمت خودرو و موتور

عددهای خودرو و موتور هم از نشانی‌های عمومی خوانده می‌شوند. هر تیپ و مدل یک عدد برای همهٔ ایران دارد و نشانی‌اش همان نشانی صفحه‌اش است؛ سال در تقویم خودِ تیپ است.

https://api.nemuda.com/api/market/vehicles/meta
https://api.nemuda.com/api/market/vehicles/index
https://api.nemuda.com/api/market/vehicles/{category}
https://api.nemuda.com/api/market/vehicles/{category}/{brand}
https://api.nemuda.com/api/market/vehicles/{category}/{brand}/{model}
https://api.nemuda.com/api/market/vehicles/{category}/{brand}/{model}/{year}

مثال:

https://api.nemuda.com/api/market/vehicles/car/samand/soren-plus-xu7p-petrol/1404
  • dataPoints — شمار قیمت‌هایی که عدد وسطِ آن‌هاست؛ کنار هر عدد همین را می‌گوییم.
  • windowDays — در هر تیپ و مدل، عدد از قیمت‌های چند روز گذشته ساخته شده: ۱۴، و جایی که در ۱۴ روز کمتر از ۵۰ داده بوده بیشتر، تا ۴۲ روز. dataPoints و totalCount در همین روزها شمرده شده‌اند. برند و دسته windowDays ندارند و همیشه از ۱۴ روز گذشته‌اند. methodVersion در /api/market/vehicles/meta تاریخ این روش است، و فقط وقتی هست که عددهای خودرو و موتور با همین روش حساب شده باشند.
  • totalCount — همهٔ قیمت‌هایی که در این مدت برای همان تیپ و مدل اعلام شده، پیش از قاعده‌های قیمت.
  • price — قیمت وسط به تومان، تا سه رقم گرد شده. برای خودرو، قیمت یک خودروی کارکرده با بدنهٔ سالم؛ برای موتور، با هر وضعیتی. زیر ۱۰ داده، برای برند و دسته، و وقتی قیمت‌ها منتشر نمی‌شوند null است.
  • priceRange — نیمهٔ وسط قیمت‌ها: یک‌چهارم قیمت‌ها از low ارزان‌ترند و یک‌چهارم از high گران‌تر.
  • mileageKm — کارکرد معمول خودروها به کیلومتر، تا هزار گرد شده؛ برای موتور null.
  • exit — چقدر زود از بازار می‌رود، برای هر تیپ، برند و دسته: dataPoints شمار آن‌هایی که یک هفته پس از گذاشته شدن دوباره سراغشان رفتیم، leftWithinWeek سهمی که آن روز دیگر برای فروش نبود (تا یک‌دهم)، typical اینکه نیمی از آن‌ها کی رفته بود: under-a-week، one-to-two-weeks، over-two-weeks یا over-a-week، و windowDays روزهایی که عدد از آن‌هاست. زیر ۱۰ داده و وقتی قیمت‌ها منتشر نمی‌شوند null است.
  • modelYear — سال ساخت به شمسی؛ ۱۳۶۶ یعنی «۱۳۶۶ و قبل‌تر».
  • displayYear — سالی که صفحه و نشانی نشان می‌دهند: همان modelYear، یا سال میلادی برای تیپ میلادی.
  • yearCalendar — تقویم سال‌های این تیپ: jalali یا gregorian.
  • coverage — solid از ۳۰ داده، limited زیر آن، none بی‌عدد.
  • familySlug — نشانی خانوادهٔ این تیپ زیر برندش (مثل /car/peugeot/206)؛ null برای تیپی که خانوادهٔ خودش است.
  • conditionTier — ردهٔ قیمتی که نسبت‌های بدنه از آن آمده‌اند، از ۰ تا ۳؛ برای موتور null.
  • conditionFactors — نسبت‌های بدنه در هر رده، که قیمت هر خودرو بر آن تقسیم شده، با تاریخ اندازه‌گیری.
  • figuresHidden — دسته‌هایی که قیمتشان فعلاً منتشر نمی‌شود؛ نام‌ها و شمار داده‌ها می‌مانند.

برای ذکر نام همان قاعدهٔ «مجوز و ذکر نام» در پایین: نام «نمودا»، پیوند به صفحهٔ همان تیپ و مدل، و تاریخ عدد. مثلاً: «پژو ۲۰۶ تیپ ۲ مدل ۱۴۰۰ کارکرده با بدنهٔ سالم، … (نمودا، تاریخ، شمار داده)».

مجوز و ذکر نام

عددهای نمودا با مجوز CC BY 4.0 آزادند؛ می‌توانید آن‌ها را بازنشر کنید یا در برنامه، گزارش و پژوهشتان به کار ببرید، حتی برای کار تجاری. فقط هر جا عددی را نشان می‌دهید، این سه را هم بیاورید: نام «نمودا»، پیوند به صفحهٔ همان عدد در سایت نمودا، و تاریخ عدد (computedAt).

هر صفحه نشانی‌اش را در خط اول نسخهٔ متنی‌اش می‌گوید، و صفحهٔ «روش و تعریف‌ها» یک مثال کامل از ذکر نام دارد.

«قیمت و دلار» فقط روی صفحه‌ها و در تصویرهای کانال تلگرام کشیده شده و به شکل داده منتشر نمی‌شود. خط دلار در «قیمت و دلار» از داده‌های نمودا نیست و مجوز استفادهٔ آزاد شامل آن نمی‌شود.

«تغییر قیمت کالاها» فقط روی صفحه‌ها و در تصویرهای کانال تلگرام کشیده شده و به شکل داده منتشر نمی‌شود؛ خط دلاری که می‌شود کنارش دید از داده‌های نمودا نیست و مجوز استفادهٔ آزاد شامل آن نمی‌شود.

این عدد را در سایت خودتان نشان دهید

هر صفحهٔ یک جا که عدد دارد و عددش با ویژگی‌ها ساخته نشده، کارتی هم دارد: یک تصویر SVG با نام آن جا، عددش، تعداد داده‌ها، تاریخ و نام نمودا. اسکریپتی ندارد، چیزی از سایت شما نمی‌خواند و هر بار که عددها دوباره حساب می‌شوند به‌روز می‌شود. نشانی‌اش نشانی همان صفحه است با /embed در اول و .svg در آخر:

https://nemuda.com/embed/index.svg
https://nemuda.com/embed/tehran-province/tehran.svg

کد آمادهٔ کارت، با پیوند به همان صفحه، در «دربارهٔ این عدد» صفحه‌هایی است که به‌احتمال زیاد می‌مانند: کل ایران، و هر استان، شهر یا محله‌ای که عددش از ۳۰ داده یا بیشتر ساخته شده؛ صفحهٔ یک جا فقط تا وقتی هست که خودش یا جایی در آن عدد دارد. اگر صفحهٔ کارتی برود، به‌جای کارت تصویری بی‌عدد با نام نمودا نشان داده می‌شود، نه تصویری شکسته. صفحه‌ای که عددش با ویژگی‌ها ساخته شده کارت ندارد. کد کل ایران این است:

<a href="https://nemuda.com/"><img src="https://nemuda.com/embed/index.svg" alt="قیمت هر متر آپارتمان در ایران، از نمودا" width="360" height="146"></a>

برای دستیارها و برنامه‌های متنی

هر صفحه نسخهٔ متنی هم دارد: به آخر نشانی صفحه /index.txt را اضافه کنید. خط اول آن می‌گوید به کدام صفحه ارجاع بدهید و یک خط زمان محاسبه را به شکلی می‌دهد که برنامه بخواند. خلاصهٔ همهٔ این‌ها برای برنامه‌ها و دستیارها در llms.txt است.

برای خواندن عددها کنار هم، بی‌برنامه، گزارش ماهانه همه را در یک صفحه دارد.

چند بار بپرسید

عددها هر شش ساعت یک بار دوباره حساب می‌شوند؛ پرسیدن بیشتر از آن عدد تازه‌ای نمی‌دهد. زمان آخرین محاسبه را /api/market/meta می‌گوید؛ همان را بپرسید و فقط وقتی computedAt عوض شد بقیه را دوباره بخوانید.