مشخصات و نمای کلی

کد دسترسی API

پس از ثبت نام و ورود به پنل کاربری یک api key اختصاصی که ترکیبی از حروف و عدد انگلیسی است برای شما تولید میشود برای احراز هویت براحتی فقط کافیست در انتهای آدرس زیر با استفاده از کلمه access_keyکد اختصاصی خودتان را وارد کنید.


کد دسترسی خود را مشابه مثال زیر اضافه کنید

                            https://apilayer.ir/live/api
? access_key = YOUR_ACCESS_KEY
کد دسترسی API

پاسخ برگشتی از api بصورت یک JSON کد بسیار سبک و قابل درک است که شامل یکسری خصوصیات میباشد که در بخش زیر تصویر آن آورده شده است.


نمونه مثال پاسخ برگشتی API

                            {
"success" : success, "terms": "https://apilayer.ir/terms", "privacy": "https://apilayer.ir/privacy", "timestamp": 1430401802, "source": "USD", "quotes": { "USDAED": 3.672982, "USDAFN": 57.8936, "USDALL": 126.1652, "USDAMD": 475.306, "USDANG": 1.78952, "USDAOA": 109.216875, "USDARS": 8.901966, "USDAUD": 1.269072, "USDAWG": 1.792375, "USDAZN": 1.04945, "USDBAM": 1.757305, [...] } }

در این حالت با توجه به ارز مبدا که در این مثال همان source میباشد که دلار است، در پاسخ آبجکت quotes نسبت دلار به سایر ارزها را برمیگرداند همچنین مقدار timestamp زمان برگشت یا تاریخ به همراه ساعت را برمیگرداند.

خصوصیات پاسخ برگشتی API

api برگشتی apilayer.ir بصورت JSON میباشد که بسیار پرکاربرد و در استفاده برنامه نویسی راحت هستند.

در جدول زیر خصوصیات برگشتی از API به تفسیر آمده است.

خصوصیت توصیف
success با توجه به اینکه کوئری شما درست اجرا شده است پاسخ true یا false برمیگرداند
terms یک لینک جهت ارجاع به بخش شرایط و ضوابط استفاده apilayer.ir برمیگرداند
privacy یک لینک جهت ارجاع به بخش سیاست های apilayer.ir برمیگرداند
timestamp زمان دقیق جمع آوی اطلاعات درخواستی شما از API را برمیگرداند
source نشان دهنده ارز مبدا است یعنی ارزی که میخواهید نسبت آن به سایر ارزها را داشته باشید. پیش فرض (USD)
quotes شامل کلیه ارزها میباشد که نسبت آنها به ارز مبدا برگردانده شده است که بصورت جفت ارز نمایش داده میشود.
ارز های قابل پشتیبانی

یک لیست کامل از کلیه ارزها بصورت JSON در این وبسایت قابل دسترس میباشد

جهت دسترسی به لیست آنها که شامل 3 حرف هستند میتوانید براحتی کد API خود را بصورت لینک زیر ارسال کنید.


                            https://apilayer.ir/list
? access_key = YOUR_ACCESS_KEY

نمونه مثال بازگشتی از درخواست بالا

                            {
"success" : success, "terms": "https://apilayer.ir/terms", "privacy": https://apilayer.ir/privacy, "currencies": { "AED": "United Arab Emirates Dirham", "AFN": "Afghan Afghani", "ALL": "Albanian Lek", "AMD": "Armenian Dram", "ANG": "Netherlands Antillean Guilder", [...] } }
خصوصیات پاسخ برگشتی API
خصوصیت توصیف
success با توجه به اینکه کوئری شما درست اجرا شده است پاسخ true یا false برمیگرداند
terms یک لینک جهت ارجاع به بخش شرایط و ضوابط استفاده apilayer.ir برمیگرداند
privacy یک لینک جهت ارجاع به بخش سیاست های apilayer.ir برمیگرداند
currencies کلیه ارزهایی که توسط apilayer.ir پشتیبانی میشود را برمیگرداند.
ارتباط API

بصورت کلی استفاده از API ها به 5 صورت قابل استفاده میباشد که در هر مورد اطلاعات متفاوتی را در اختیار شما میگذارد.

در این بخش خلاصه ای از نحوه استفاده از آنها را مشاهده میکنید و در بخش ویژگی های API بطور کامل به توضیح هر یک خواهیم پرداخت.

آدرس پایه و ثابت همه درخواست ها
                            https://apilayer.ir/api
                        

5 صورت کلی استفاده از api ها بصورت زیر میباشد:

                            // "live" جهت دریافت آخرین نرخ ارز
                            https://apilayer.ir/api/live
                            
// "historical" جهت دریافت تاریخچه نرخ ارز https://apilayer.ir/api/historical?date=YYYY-MM-DD
// "convert" جهت دریافت تبدیل نرخ ارز https://apilayer.ir/api/convert?from=EUR&to=GBP&amount=100
// "timeframe" جهت دریافت نرخ ارز در زمان مشخص https://apilayer.ir/api/timeframe?start_date=2015-01-01&end_date=2020-02-11
// "change" جهت دریافت تغییرات نرخ ارز (مارجین،درصدها) https://apilayer.ir/api/change?currencies=USD,EUR
مهم :

لطفا توجه داشته باشید که موارد ذکر شده در بالا بدون در نظر گرفتن کد api میباشد، بدیهی است که در هنگام استفاده میبایست کد api را هم به درخواست خود اضافه کنید.

پروتکل HTTPS

کلیه درخواست مبتنی بر پروتکل Https میباشد که پروتکل امنیتی جهت ارسال و دریافت درخواست ها میباشد.


کدهای خطا

اگر درخواست شما با خطا مواجه شود، api یک کد خطای 3 رقمی و یک توضیح در بخش info به شما نمایش خواهد داد.

نمونه خطا : یک نمونه خطا از زمانیکه تعداد درخواست های ماهیانه کاربر به اتمام رسیده است.

                            {
"success" : false, "error": { "code": 104, "info": "Your monthly usage limit has been reached. Please upgrade your subscription plan." } }
خطاهای عمومی API
کد توصیف
404 User requested a resource which does not exist
101 User did not supply an access key or supplied an invalid access key
103 User requested a non-existent API function
104 User has reached or exceeded his subscription plan's monthly API request allowance
105 The user's current subscription plan does not support the requested API function
106 The user's query did not return any results
102 The user's account is not active. User will be prompted to get in touch with Customer Support
202 User entered an invalid Source Currency
301 [historical] User did not specify a date
302 [historical, convert] User entered an invalid date
401 [convert] User entered an invalid "from" property
402 [convert] User entered an invalid "to" property
403 [convert] User entered no or an invalid "amount" property
501 [timeframe, convert] User did not specify a Time-Frame
502 [timeframe, convert] User entered an invalid "start_date" property
503 [timeframe , convert] User entered an invalid "end_date" property
504 [timeframe, convert] User entered an invalid Time-Frame
505 [timeframe] The Time-Frame specified by the user is too long - exceeding 365 days
ویژگی های API

نرخ زنده ارز