Crazy Yangon Traffic: Traffic monitoring and reporting app for Yangon
Latest commit 88f36fd Jun 21, 2014 @eimg Merge pull request #2 from sHa92/master
Fix typo from @sHa92
Permalink
Failed to load latest commit information.
LICENSE Initial commit Jun 18, 2014
README.md

README.md

Cyantra API

Cyantra ဆိုသည်မှာ၊ ရန်ကုန်မြို့၏ ယာဉ်ကြောပိတ်ဆို့မှုအခြေအနေများကို အချိန်နှင့်တစ်ပြေးညီ အများသိရှိနိုင်စေရန်၊ အများမှပင် သတင်းပေးပို့နိုင်သည့် App တစ်ခုဖြစ်ပါသည်။ cyantra.co တွင် HTML5 Support လုပ်သည့် မည်သည့် Web Browser ဖြင့်မဆို အသုံးပြုနိုင်ပါသည်။

Cyantra ကို သည်မည်သည့်အကျိုးအမြတ်မှ မမျှော်မှန်းပဲ၊ မည်သူမဆို (အခမဲ့) ရယူအသုံးပြုနိုင်ရန် ရည်ရွယ်တည်ဆောက်ထားခြင်း ဖြစ်ပါသည်။ ထို့အပြင် အခြား စိတ်ဝင်စားသူ Developer များမှ Mobile Devices အမျိုးမျိုးအတွက် Native App များ တည်ဆောက်ခြင်း၊ မိမိတို့၏ App များတွင် Traffic Information ကို ထည့်သွင်း တည်ဆောက်ခြင်း၊ စသည့်ကိစ္စရပ်များတွင် အသုံးပြုနိုင်စေရန် ရည်ရွယ်၍ ဤ API အသုံးပြုမှု လမ်းညွှန်ကို ဖော်ပြပေးလိုက်ပါသည်။

သတိပြုရန်

ဤ API သည် စမ်းသပ်ဆဲအဆင့်ဖြစ်သဖြင့် အချိန်မရွေး ပြောင်းလဲခြင်း၊ ဖြည့်စွက်ခြင်း၊ ပြင်ဆင်ခြင်းများ ရှိနိုင်ပါသည်။ သို့ရာတွင် အသေးအမွှား အပြောင်းအလဲများသာ ဖြစ်ပါသည်။ ကြီးမားသည့် Major Changes များ ရှိပါက၊ လက်ရှိ API ကို မထိခိုက်စေပဲ နောက် API Version အသစ်အဖြစ် စီမံပေးမည်ဖြစ်ပါသည်။

API ရယူအသုံးပြုမှုကို ယခုအချိန်တွင် ကန့်သတ်မထားသော်လည်း၊ API Request များ များပြားလာသည့်အခါ Resource Allocation ကိစ္စ စီမံနိုင်ရန်အတွက် API Key ရှိသူကိုသည် ရယူခွင့် ပြုသွားမည်ဖြစ်ပါသည်။ API Key ကို မည်သူမဆို အခမဲ့ မှတ်ပုံတင်ရယူခွင့် ပြုမည်ဖြစ်ပါသည်။

ယခုအခါ ရယူခွင့်ပြုထားသည့် API Request အရေအတွက်ကို ကန့်သတ်မထားသော်လည်း Server ၏ Resource အသုံးပြုမှုကို ငဲ့ကွက်၍၊ API ရယူအသုံးပြုသူဘက်မှ Request များကို စီစစ်ပြုလုပ်စေလိုပါသည်။ Client ၏ အလုပ်လုပ်ပုံ အားနည်းချက်ကြောင့် API Request များကို လိုသည်ထက်ပြုလုပ်နေကြောင်း တွေ့ရှိရပါက API ရယူခွင့်ကို ရုတ်သိမ်းသွားမည်ဖြစ်ပါသည်။

သတင်းပေးပို့ချက်များကို ရယူခြင်း

နောက်ဆုံးသတင်းပေးပို့ချက်များကို အောက်ပါ API URL ကို အသုံးပြုခြင်းအားဖြင့် ရယူနိုင်ပါသည်။

http://cyantra.co/api/get

Cyantra မှ (ယနေ့) သတင်းပေးပို့ချက်များထဲမှ နောက်ဆုံးပေးပို့ချက် (၂၀) ကို JSON Format ဖြင့် ပြန်လည် Respond ပြုလုပ်မည် ဖြစ်ပါသည်။ ပါဝင်မည့် အချက်အလက်များမှာ အောက်ပါအတိုင်းဖြစ်ပါသည်။

{
    name: [Place Name],
    status: [Current Status],
    reported_at: [Reported Time],
    recent: [Time Diff],
    remark: [Event Remark]
}
  • [Place Name] - တည်နေရာ
  • [Currnnt Status] - ပိတ်ဆို့မှု အခြေအနေ (0 - No Report, 1 - Normal or Clean, 2 - Bad Traffic, 3 - Worst Traffic)
  • [Reported Time] - သတင်းပေးပို့သည့်အချိန် (Format - hh:mm am/pm)
  • [Time Diff] - သတင်းပေးပို့ထားသည့်အချိန်နှင့် လက်ရှိအချိန်၊ ကွာခြားချိန် နာရီကို တွက်ချက်ဖော်ပြပါသည်
  • [Event Remark] - ယာဉ်ကြောပိတ်ဆို့ရခြင်း အကြောင်းရင်း အခြေအနေကို (စာဖြင့်မဟုတ်ပဲ) ကိန်းဂဏန်းဖြင့် ဖော်ပြပါသည်။ ကိန်းဂဏန်း တစ်ခုချင်းစီ၏ အဓိပ္ပါယ်မှာ အောက်ပါတိုင်းဖြစ်ပါသည်။
  1. ရေကြီးနေသည်
  2. မီးပွိုင့်ပျက်နေသည်
  3. ယာဉ်မတော်တဆဖြစ်နေသည်
  4. ကျောင်းလွှတ်ချိန်
  5. လမ်းပြင်နေသည်
  6. ရေမြောင်းဖော်နေသည်
  7. မြေအောက်ပိုက်လိုင်းပြင်နေသည်
  8. စည်းကမ်းမဲ့ယာဉ်ရပ်ထားသည်
  9. ပွဲအခမ်းအနားရှိနေသည်
  10. ကားပျက်နေသည်

မှတ်ချက် ။ ။ နောင်တွင် မှတ်ချက်ကို နှစ်သက်သလို ထည့်သွင်းခွင့် ပြုရန် ရည်ရွယ်ထားပါသည်။ လက်ရှိတွင် အသုံးပြုသူများ ပေးပို့လာသည့် မှတ်ချက်များကို စီစစ်နိုင်ခြင်း မရှိသေးပါသဖြင့် ပုံသေသတ်မှတ်ထားသည့် မှတ်ချက်ကိုသာ ခွင့်ပြုပါသည်။

ယနေ့ပေးပို့ထားသည့် သတင်းပေးပို့ချက်များကိုသာ ရရှိမည်ကို သတိပြုပါ။ ယခင်နေ့များက ပေးပို့ထားသည့် သတင်းပို့ချက်များကို ရယူနိုင်သည့် API မရှိသေးပါ။

နောက်ဆုံးသတင်းပေးပို့ချက်ကို အခု (၂၀) ထက်ပိုလိုချင်ပါက ယခုလို ရယူနိုင်ပါသည်။

http://cyantra.co/api/get/20

20 နေရာတွင် နှစ်သက်ရာ စမှတ်ကို ထည့်သွင်းပေးနိုင်ပါသည်။ သတိပြုပါ။ 20 သည် အရေအတွက် မဟုတ်ပါ။ စမှတ်ဖြစ်ပါသည်။

နောက်ဆုံးသတင်းပေးပို့ချက်များမှ ပြီးခဲ့သည့် (၁) နာရီအတွင်း ပေးပို့ထားချက်များကိုသာ လိုချင်ပါက ယခုလို ရယူနိုင်ပါသည်။

http://cyantra.co/api/get/recent

နောက်ဆုံးသတင်းပေးပို့ချက်များမှ ယာဉ်ကြောပိတ်ဆို့နေကြောင်း သတင်းပေးပို့ချက်များကိုသာ ရယူလိုပါက ယခုလို ရယူနိုင်ပါသည်။

http://cyantra.co/api/get/bad

နောက်ဆုံးသတင်းပေးပို့ချက်များမှ ယာဉ်ကြောရှင်းနေကြောင်း သတင်းပေးပို့ချက်များကိုသာ ရယူလိုပါက ယခုလို ရယူနိုင်ပါသည်။

http://cyantra.co/api/get/normal

နောက်ဆုံးသတင်းပေးပို့ချက်များမှ သတ်မှတ်နေရာဒေသများအတွက်သာ ရယူလိုပါက ယခုလို ရယူနိုင်ပါသည်။

http://cyantra.co/api/get/mine?i=ဆရာစံလမ်းဆုံ,တာမွေအဝိုင်း,ယုဇနပလာဇာ

ရယူလိုသည့် ဒေသစာရင်းကို API Request နှင့်အတူ i=place1,place2 ပုံစံ Format ဖြင့် တွဲဖက်ထည့်သွင်းပေးရခြင်း ဖြစ်ပါသည်။ i ဆိုသည်မှာ Input Data ၏ အတိုကောက် ဖြစ်ပါသည်။

သတင်းပေးပို့ချက်များ ရယူရာတွင် အသုံးပြုရမည့် Request Method ကို ကန့်သတ်မထားပါ။ နှစ်သက်ရာ အသုံးပြုနိုင်ပါသည်။ သို့ရာတွင် Request URL Size ကို ငဲ့ကွက်ရမည်ဖြစ်သဖြင့် api/get/mine Request အတွက် POST ကို အသုံးပြုသင့်ပါသည်။ ကျန် API Request များအတွက် GET ကို အသုံးပြုသင့်ပါသည်။

အကယ်၍ ပြုလုပ်လာသည့် API Request အတွက် Respond ပြန်ပေးရန် အချက်အလက်မရှိပါက --

{ empty: true }

-- ကို ပြန်ပေးမှာ ဖြစ်ပါသည်။

နေရာဒေသအားလုံး၏ အမည်စာရင်းသက်သက်ကိုသာ ရယူလိုလျှင် အောက်ပါအတိုင်း ရယူနိုင်ပါသည်။

http://cyantra.co/api/get/places

နေရာဒေသတစ်ခု၏ အခြေအနေကို ရယူခြင်း

နေရာဒေသတစ်ခု၏ လက်ရှိယာဉ်ကြောပိတ်ဆို့မှု အခြေအနေကို ယခုလို ရှာဖွေရယူနိုင်ပါသည်။

http://cyantra.co/api/search?p=တာမွေအဝိုင်း

ရယူလိုသည့် နေရာဒေသအမည်ကို p နှင့် တွဲဖက်ပေးရခြင်းဖြစ်ပါသည်။ p ဆိုသည်မှာ Place ၏ အတိုကောက်ဖြစ်ပါသည်။ သတ်မှတ်နေရာဒေသအတွက် နောက်ဆုံး သတင်းပေးပို့ချက် (၄) ခုကို Respond ပြန်ပေးမှာဖြစ်ပါတယ်။ Respond Format မှာ အထက်တွင်ဖော်ပြခဲ့သည့် Format အတိုင်းပင် ဖြစ်ပါသည်။

{
    name: [Place Name],
    status: [Current Status],
    reported_at: [Reported Time],
    recent: [Time Diff],
    remark: [Event Remark]
}

ထူးခြားချက်တစ်ခုရှိပါသည်။ ရှာဖွေရယူလိုသည့် နေရာဒေသအတွက် သတင်းပေးပို့ချက်များ ယခင်က တစ်ကြိမ်မှ မရှိဖူးလျှင် Cyantra က အဆိုပါဒေသကို ထည့်သွင်းပေးသွားမှာ ဖြစ်ပါသည်။ ပြန်လည်ပေးပို့မည့် Respond Format မှာ အောက်ပါအတိုင်းဖြစ်ပါသည်။

{ err: 1, place: "တာမွေအဝိုင်း" }

အသစ်ထည့်သွင်းထားသည့် နေရာဒေသအတွက် သတင်းပေးပို့ထားသည့် ယာဉ်ကြောပိတ်ဆို့မှုအခြေအနေ မရှိသေးသဖြင့် အခြားအချက်အလက်များ မပါဝင်ပဲ၊ အမည် တစ်ခုတည်းသာ ပါဝင်ခြင်း ဖြစ်ပါသည်။ err: 1 တန်ဖိုးကို စီစစ်ခြင်းအားဖြင့် ရှာမတွေ့သောကြောင့် အသစ်တည်ဆောက်သွားကြောင်း သိရှိနိုင်ပါသည်။

Cyantra သည် ရန်ကုန်မြို့အတွက်သာ ရည်ရွယ်တည်ဆောက်ထားခြင်းဖြစ်ပါသည်။ သို့ရာတွင် API မှာ သတင်းပေးပို့လာသည့် နေရာဒေသကို စီစစ်ထားခြင်းမရှိသဖြင့် အခြားမြို့များနှင့် ပြည်ပမှလည်း ပေးပို့နိုင်ပါသည်။ နေရာဒေသအားလုံး၏ အချက်အလက်များကို တာဝန်ယူစီမံရန် Resource အလုံအလောက် မရှိသေးပါသဖြင့် ရန်ကုန်နှင့် သက်ဆိုင်သည့် အချက်အလက်ဖြစ်ကြောင်း Client ဘက်မှ စီစစ်ပေးပို့စေလိုပါသည်။ နောင်တွင် အခြားနေရာ ဒေသများကိုလည်း Support လုပ်ရန်အစီအစဉ်ရှိသော်လည်း ယခုအဆင့်တွင် ရန်ကုန်မှမဟုတ်သည့် အချက်အလက်များ ပေးပို့လာပါက ပယ်ဖျက်သွားမည်ဖြစ်ပါသည်။

လက်ရှိအခြေအနေ သတင်းပေးပို့ခြင်း

ယာဉ်ကြောပိတ်ဆို့မှုအခြေအနေကို အောက်ပါ အတိုင်း သတင်းပေးပို့နိုင်ပါသည်။

http://cyantra.co/api/update?p=တာမွေအဝိုင်း&s=2&c=2

ယာဉ်ကြောပိတ်ဆို့မှုအခြေအနေ သတင်းပေးပို့လိုသည့် တည်နေရာကို p နှင့် တွဲဖက်ထည့်သွင်းပေးရပါသည်။ ပိတ်ဆို့မှု အခြေအနေကို Status ၏ အတိုကောက်ဖြစ်သည့် s နှင့် တွဲဖက်ထည့်သွင်းပေးရပါသည်။ 1 (Normal or Clean) သို့မဟုတ် 2 (Bad Traffic) နှင့် 3 (Worst Traffic) တို့ကို လိုအပ်သလို တွဲဖက် ထည့်သွင်းပေးနိုင်ပါသည်။ ယာဉ်ကြောပိတ်ဆို့ရခြင်း အကြောင်းရင်းမှတ်ချက် (Comment) ကို c နှင့် တွဲဖက်ထည့်သွင်းပေးနိုင်ပါသည်။ အကြောင်းရင်း (၁၀) ချက်ကို နံပါတ်စဉ်အတိုင်း အထက်တွင် ဖော်ပြခဲ့ပြီးဖြစ်ပါသည်။

သတင်းပေးပို့ခြင်းလုပ်ငန်း အောင်မြင်ပါက အခုလို Respond ကို လက်ခံရရှိမည်ဖြစ်ပါသည်။

{ err: 0, remark: "ကားပျက်နေသည်" }

ကျန်အချက်အလက်များဖြစ်သည့် နေရာဒေသအမည်၊ အခြေအနေတို့ကို ပြည်လည်ပေးပို့တော့မည် မဟုတ်ပါ။စနစ်မှ ကြိုတင်သတ်မှတ်ထားသည့် မှတ်ချက်ကိုသာ စာအနေနှင့် ပြန်လည်ပေးပိုခြင်းဖြစ်ပါသည်။

ပယ်ဖျက်စေလိုသည့် နေရာဒေသကို အချက်ပြခြင်း

မသက်ဆိုင်သည့် နေရာဒေသများ၊ အသုံးပြုသူများ စမ်းသပ်ထည့်သွင်းထားသည့် မဆီလျှော်သည့် အချက်အလက်များ ရှိလာပါက အောက်ပါအတိုင် ပယ်ဖျက်ပေးပါရန် အချက်ပြမှတ်သားနိုင်ပါသည်။

http://cyantra.co/api/flag?p=ပေါက်ကရလေးဆယ်

ပယ်ဖျက်စေလိုသည့် ဒေသအမည်ကို p နှင့် တွဲဖက်ပေးရပါသည်။

ဆက်လက်၍ တိုးမြှင့်ဖြည့်စွက်ရန် ရည်ရွယ်ချက်များ

Cyantra ကို ယာဉ်ကြောပိတ်ဆို့မှု သတင်းပို့ရန်အတွက်သာမဟုတ်ပဲ၊ စည်းကမ်းမဲ့ ယာဉ်ရပ်နားမှုများ၊ စည်းကမ်းမဲ့ ယာဉ်မောင်းနှင်မှုများ၊ ယာဉ်မတောတဆမှုများကို အချိန်နှင့် တစ်ပြေးညီ သတင်းပေးပို့နိုင်စေရန် ဆက်လက်တိုးချဲ့သွားဖို့ ရည်ရွယ်ပါသည်။ ထို့အပြင် ယာဉ်မောင်းနှင်မှုဆိုင်ရာ လမ်းကြော/လမ်းကြောင်း အကြံပြုချက်များ၊ ယာဉ်စည်းကမ်းဆိုင်ရာ သိမှတ်ဖွယ်ရာများကိုလည်း အသုံးပြုသူများအကြား တစ်ဦးနှင့်တစ်ဦး အပြန်အလှန်ဝေမျှနိုင်စေသည့် လုပ်ဆောင်ချက်များလည်း ဆက်လက်တိုးချဲ့သွားရန် ရည်ရွယ်ထားပါသည်။ Client App တည်ဆောက်သူများ ဘက်မှလည်း Map နှင့် Location ဆိုင်ရာလုပ်ဆောင်ချက်များဖြင့် ပြည့်စုံအသုံးဝင်အောင် အဆက်မပြတ် တိုးမြှင့်သွားသင့်ပါသည်။

API အဆင့်မြှင့်တင်မှုများရှိလာပါက ဤနေရာတွင် ဆက်လက်ဖော်ပြပေးသွားမည်ဖြစ်ပါသဖြင့် ထပ်မံလာရောက်လေ့လာနိုင်ပါသည်။ App အလုပ်လုပ်ပုံနမူနာအနနှင့်လည်း cyantra.co တွင် လွှင့်တင်ပေးထားသည့် Web App ကို လေ့လာနိုင်ပါသည်။

ဆက်သွယ်ရန်

API နှင့် ပက်သက်၍ အသေးစိတ်သိရှိလိုသည်များ၊ ဖြည့်စွက်ပြင်ဆင်ပေးရန် တောင်းဆိုလိုသည်များများ၊ ဆက်လက်တိုးချဲ့ရန်အတွက် အကြံပြုလိုသည်များ ရှိပါက eimg@fairwayweb.com သို့ Email ပေးပို့၍ ဆက်သွယ်နိုင်ပါသည်။