API بازار بورس تهران
در این مقاله قصد داریم وب سرویس بازار بورس تهران را معرفی کنیم.
این API امکان دسترسی به مجموعه کامل اطلاعات مالی و معاملاتی بازار بورس تهران را به روش RESTful فراهم می‌کند.
احراز هویت
برای استفاده از این API لازم است که یک اشتراک تهیه کنید. بعد از تهیه اشتراک به شما یک access_token داده می‌شود که باید هنگام فراخوانی متدها آن را به عنوان Username به روش Basic Auth ارسال کنید.
برای این کار کاراکتر : را به access_token داده شده اضافه کنید و نتیجه را Base64 کرده و به همراه رشته Basic به عنوان مقدار هدر Authorization ارسال کنید.
header_value = “Basic ” + Base64(access_token + “:”)
برای مثال اگر access_token شما abcd باشد باید هدر زیر را به همراه هر درخواست ارسال کنید:
Authorization: Basic YWJjZDo=
قالب ارائه اطلاعات
پاسخ ارسالی از متدها یک سند JSON است و اطلاعات درخواستی در فیلد data ارائه خواهد شد:
{
“data”: [ … ]
}
فیلدهای از نوع Date از جنس String و با قالب YYYYMMdd و فیلدهای از نوع DateTime با قالب YYYYMMddHHmmss و با فرض منطقه زمانی ایران (UTC+3:30) هستند.
اگر مقدار فیلدی null باشد در خروجی آورده نمی‌شود.
رکوردها
هر رکورد یک کد منحصر به فرد به نام id دارد که از جنس String است. در حال حاضر کدها به شکل اعداد ترتیبی هستند اما ممکن است در آینده به شکل دیگری (مانند GUID) ارائه شوند؛ بنابر این دقت کنید که در برنامه خود با آنها حتما به شکل String رفتار کنید.
همچنین، هر رکورد یک فیلد به نام meta دارد که اطلاعاتی را درباره خود رکورد ارائه می‌کند:
{
“data”: [
{
…
“meta”: {
“version”: 283184512,
“state”: “deleted”,
“insert_date_time”: “13930714082148”,
“update_date_time”: “13930718121432”,
“delete_date_time”: “13930720220123”
}
}
]
}
فیلد version یک شماره ترتیبی از جنس Int64 است که با هر بار تغییر رکورد افزایش داده می‌شود.
فیلد state وضعیت رکورد (inserted, updated, deleted) را نشان می‌دهد. در این سیستم رکورد‌های حذف شده هیچ گاه به طور فیزیکی پاک نمی‌شوند و تنها مقدار state آنها به deleted تغییر داده می‌شود. در این حالت تنها فیلدهای id و meta برگشت داده می‌شود.
فیلدهای insert_date_time و update_date_time و delete_date_time نیز به ترتیب زمان ثبت، به روز رسانی و حذف رکورد را (در صورت وجود) نشان می‌دهند.
روش استفاده بهینه
جهت افزایش سرعت دسترسی به اطلاعات و همچنین صرفه‌جویی در مصرف پهنای باند و منابع سرور توصیه می‌شود که بعد از دریافت اطلاعات آنها را در دیتابیس خود ذخیره کرده و پس از آن با استفاده از فیلد meta.version تنها تغییرات را دریافت کنید.
برای مثال اگر شماره meta.version آخرین رکوردی که دریافت کرده‌اید 1000 باشد فراخوانی زیر تنها رکوردهایی که بعد از آن اضافه شده‌اند، تغییر کرده‌اند و یا حذف شده‌اند را برمی‌گرداند:
GET /method?_sort=meta.version&meta.version=1000&meta.version_op=gt
فیلتر کردن اطلاعات
برای محدود کردن اطلاعات دریافتی میتوانید نام یک یا چند فیلد را به همراه مقادیری که می‌خواهید نتایج بر اساس آنها فیلتر شوند ارسال کنید.
GET /method?id=100 # دریافت رکوردهایی که مقدار id آنها برابر 100 است
GET /method?id=100&name=foo # دریافت رکوردهایی که مقدار id آنها برابر 100 و مقدار name آنها برابر foo است
برای مشخص کردن این که مقدار یک فیلد مخالف مقدار مشخص شده باشد از عملگر neq استفاده کنید:
GET /method?id=100&id_op=neq # دریافت رکوردهایی که مقدار id آنها مخالف 100 است
GET /method?name=foo&name_op=neq # دریافت رکوردهایی که مقدار name آنها برابر foo نیست
برای مشخص کردن این که مقدار یک فیلد کوچکتر/کوچکتر یا مساوی/بزرگتر/بزرگتر یا مساوی مقدار مشخص شده باشد از عملگرهای lt / lte / gt / gte استفاده کنید:
GET /method?id=100&id_op=lt # دریافت رکوردهایی که مقدار id آنها کوچکتر از 100 است
GET /method?id=100&id_op=lte # دریافت رکوردهایی که مقدار id آنها کوچکتر و یا مساوی 100 است
GET /method?id=100&id_op=gt # دریافت رکوردهایی که مقدار id آنها بزرگتر از 100 است
GET /method?id=100&id_op=gte # دریافت رکوردهایی که مقدار id آنها بزرگتر و یا مساوی 100 است
برای مشخص کردن این که مقدار یک فیلد برابر یکی از مقادیر مشخص شده باشد و یا نباشد از عملگرهای in / nin استفاده کنید:
GET /method?id=100,200&id_op=in # دریافت رکوردهایی که مقدار id آنها برابر 100 و یا 200 است
GET /method?id=100,200&id_op=nin # دریافت رکوردهایی که مقدار id آنها برابر 100 و 200 نیست
GET /method?name=foo,bar&id_op=in # دریافت رکوردهایی که مقدار name آنها برابر foo و یا bar است
GET /method?name=foo,bar&id_op=nin # دریافت رکوردهایی که مقدار name آنها برابر foo و bar نیست
برای مشخص کردن این که مقدار یک فیلد در یک محدوده مشخص (و شامل مقادیر ابتدا و انتهای بازه) باشد از عملگر bw استفاده کنید:
GET /method?id=100,200&id_op=bw # دریافت رکوردهایی که مقدار id آنها بین 100 و 200 است
برای مشخص کردن این که مقدار یک فیلد شامل مقدار مشخص شده باشد یا نباشد از عملگرهای like / notlike استفاده کنید:
GET /method?name=foo&name_op=like # دریافت رکوردهایی که مقدار name آنها شامل foo باشد
GET /method?name=bar&name_op=notlike # دریافت رکوردهایی که مقدار name آنها شامل bar نباشد
برای مشخص کردن این که یک فیلد بدون مقدار باشد یا نباشد از عملگرهای null / notnull استفاده کنید:
GET /method?name_op=null # دریافت رکوردهایی که فیلد name آنها بدون مقدار باشد
GET /method?name_op=notnull # دریافت رکوردهایی که فیلد name آنها بدون مقدار نباشد
محدود کردن نتایج
برای محدود کردن نتایج میتوانید از پارامترهای _count و _skip استفاده کنید.
GET /method?_count=100 # دریافت 100 رکورد اول
GET /method?_count=100&_skip=200 # صرف نظر کردن از 200 رکورد اول و دریافت 100 رکورد بعدی
مقدار پیش فرض پارامتر _count 50 و حداکثر مقدار مجاز آن 100 است.
مرتب سازی
برای مرتب کردن اطلاعات نام فیلد و یا فیلدهایی که می‌خواهید نتایج بر اساس آنها مرتب شود را در پارامتر _sort مشخص کنید:
GET /method?_sort=name # مرتب سازی بر اساس فیلد name
GET /method?_sort=-name # مرتب سازی بر اساس فیلد name به صورت نزولی
GET /method?_sort=name,age # مرتب سازی بر اساس فیلد name و سپس بر اساس فیلد age
GET /method?_sort=name,-age # مرتب سازی بر اساس فیلد name و سپس بر اساس فیلد age به صورت نزولی
بسط دادن
اگر رکوردی یک رکورد داخلی داشته باشد به طور پیش‌فرض تنها فیلد id آن در خروجی آورده می‌شود:
GET /method
{
“data”: [
{
…
“company”: {
“id”: “164”
},
“instrument”: {
“id”: “1982”
},
…
}
]
}
برای این که بقیه اطلاعات رکورد داخلی نیز در خروجی آورده داده شود نام فیلد و یا فیلدهای مورد نظر را در پارامتر _expand مشخص کنید:
GET /method?_expand=company,instrument
{
“data”: [
{
…
“company”: {
“id”: “164”,
“name”: “ایران خودرو”,
“trade_symbol”: “خودرو”,
…
},
“instrument”: {
“id”: “3312”
“name”: “ایران خودرو”,
“code”: “IRO1IKCO0001”,
“isin”: “IRO1IKCO0008”,
…
},
…
}
]
}
خطاها
اگر هدر Authorization ارسال نشده باشد و یا access_token ارسال شده معتبر نباشد خطای 401 Unauthorized برگشت داده می‌شود.
GET /method
Authorization: Basic YWJjZDx=
HTTP/1.1 401 Unauthorized
اگر هر یک از پارامترهای ارسالی معتبر نباشد خطای 422 Unprocessable Entity برگشت داده می‌شود. در این حالت فیلد error شامل اطلاعات بیشتری در مورد خطای رخ داده است.
GET /method?company_id=foo
HTTP/1.1 422 Unprocessable Entity
{
“error”: {
“code”: “invalid_company_id”,
“message”: “There is no company with the specified id.”,
“parameter”: “company_id”,
}
}
با سلام.. اینکه تیکه کد نوشتین زیاد به کار ما نمیاد یک پروژه عملی ویندوزی یا تحت وب رو انجام بدین باتشکر
ممنون از نظرتون
حتما در روزهای آتی این کار انجام مشود و فیلم های آموزشی کامل هم قرار میگیرد
از کجا باید اشتراک API بورس رو تهیه کنم؟کارگزاریها که دسترسی نمیدن!!!!!
انتهای این مطلب از طریق لینک منبع میتوانید اشتراک را تهیه کنید
سلام عالیییییییییییییییییییییییییییییییییییی
تشکر
و اینکه اشتراک رو باید از کجا تهیه کنم و قیمتش چقدره؟
روی لینک منبع کلیک کردم اما اونجا توضیح نداده بود چطوری باید اشتراک بگیرم
ممنون میشم توضیح بدید