Permalink
Switch branches/tags
Nothing to show
Find file Copy path
Fetching contributors…
Cannot retrieve contributors at this time
620 lines (482 sloc) 16.2 KB

Jinma API 文件

目錄

簡介

Jinma API 幫你快速開發地理資訊服務,迅速且容易。

在 Jinma 上發表訊息都是公開且免費,就這麼簡單。

建立你的應用程式

針對每種使用情境,建立對應的應用程式,例如:「台灣超威天氣」用來顯示天氣開放資料,「美食記」用來製作美食記錄。

假如你是唯一的資料提供者,只需要進行下一步驟,直接用瀏覽器就可以拿到你的 access token。不必實作登入介面,好!

假如你想讓其他使用者也能提供資料,由於 Jinma 遵循 OAuth 2.0 規格,所以你的應用程式的確能提供其他使用者,登入並使用 Jinma 平台。

建立應用程式

在這裡登入並建立 Jinma 應用程式。OAuth 2 登入流程需要 App ID ($APP_ID) 和 Redirect URI ($REDIRECT_URI) 兩個參數。

OAuth 2 流程

  1. 呈現此授權頁面給使用者: https://www.jinma.io/OAuth2Auth?ClientID=$APP_ID&RedirectURI=$REDIRECT_URI 行動應用程式須採用 in-app browser tab,即 iOS 的 SFSafariViewController 或 Android 的 Custom Tabs。 注意:你不應使用 webview 來呈現這個 /OAuth2Auth 頁面。 你可以到 OAuth 2.0 for Native Apps 瞭解更多細節。

  2. 轉址的 URI 會回傳 Code 參數。接著你就使用 https://www.jinma.io/OAuth2Token?ClientID=$APP_ID&Code=$CODE) 來認證這個 code,最後獲得使用者的 access token (AccessToken)。

curl "https://www.jinma.io/OAuth2Auth?ClientID=$APP_ID&RedirectURI=$REDIRECT_URI"

curl "https://www.jinma.io/OAuth2Token?ClientID=$APP_ID&Code=$CODE"

使用者

/Me

取得使用者 ID 和個人圖像。

值得一提的是,你可以使用 ThirdPartyID 轉成使用者的社群網路個人頁面,其中 Twitter 帳號以 tw: 開頭,而 Facebook 帳號以 fb: 開頭。

Language 值則是使用者登入流程中的語言偏好設定,也會被用於 Jinma 的頁面,例如:使用者設定。你也可以運用這個值,來設定應用程式介面語系。

HTTP 要求

GET https://www.jinma.io/Me

參數

參數 說明
Token 使用者的 Token

範例

curl -G "https://www.jinma.io/Me" \
 -d "Token=$TOKEN_OF_USER"

上述指令,會回傳 JSON 結構如下:

{
  "User": {
    "ID": "12UHuwvubMS2n",
    "Name": "JinmaAPI",
    "Picture": "https://pbs.twimg.com/profile_images/872802470677762048/hsmbLx4I_normal.png",
    "ThirdPartyID": "tw:3689630718",
    "Privacy": "1",
    "Language": "en"
  },
  "App": {
    "ID": "167VMeshFbCnk",
    "Name": "Jinma API Tutorial",
    "Icon": "https://pbs.twimg.com/profile_images/872802470677762048/hsmbLx4I_400x400.png",
    "MarketingURI": "https://jinmaapi.github.io"
  }
}

公開性

在 Jinma 上發表的訊息都是公開可見的。

然而,我們明白「存取單一使用者在地圖上發表過的訊息」,可能造成嚴重的隱私性問題。因此,用於存取單一使用者訊息的 API(例如:/MsgsByGeo*User)預設為需要使用者的 access token。

換句話說,只有使用者授權了你的應用程式,你才能提供個別使用者發表過的訊息。

相反地,假若你的使用者帳號只打算提供公開的開放資料,與個人隱私無關,你可以在使用者設定頁面中,切換為「公開」帳號,那麼存取你帳號發表訊息的 API 就不需要你的 access token 了!也就是說,任何人都可以自由取用了!好!

POST 訊息

/MsgCreate

在給定地理位置,建立一個新訊息。

HTTP 要求

POST https://www.jinma.io/MsgCreate

參數

參數 說明
Lat 緯度
Lng 經度
Body 訊息內容
Token 使用者的 Token

範例

curl "https://www.jinma.io/MsgCreate" \
  -F "Lat=27.994401411046145" \
  -F "Lng=-69.78515625" \
  -F "Body=Hello, world" \
  -F "Token=$TOKEN_OF_USER" \
  -X POST

上述指令,會回傳 JSON 結構如下:

{
  "ID": "11dVJp2kqop7X",
  "User": {
    "ID": "12UHuwvubMS2n",
    "Name": "JinmaAPI",
    "Picture": "https://pbs.twimg.com/profile_images/872802470677762048/hsmbLx4I_normal.png",
    "ThirdPartyID": "tw:3689630718",
    "Privacy": "1"
  },
  "Time": 1514210677.908,
  "Body": "Hello, world",
  "Lat": 27.994401411046145,
  "Lng": -69.78515625,
  "SKF64": 1514210677.908,
  "App": {
    "ID": "167VMeshFbCnk",
    "Name": "Jinma API Tutorial",
    "Icon": "https://pbs.twimg.com/profile_images/872802470677762048/hsmbLx4I_400x400.png",
    "MarketingURI": "https://jinmaapi.github.io"
  }
}

注意:/MsgsBy***可能不會立即回傳才剛用 /MsgCreate 發表的訊息。要在你的應用程式介面上,立即顯示出 /MsgCreate 結果的話,可以直接把回傳的訊息物件,呈現到應用程式介面上。

/MsgUpdate

更新/編輯訊息。

HTTP 要求

POST https://www.jinma.io/MsgUpdate

參數

參數 說明
MsgID 訊息 ID
Body 編輯完的訊息
Token 作者的 Token

範例

curl "https://www.jinma.io/MsgUpdate" \
  -F "MsgID=11dVJp2kqop7X" \
  -F "Body=Hello, Jinma" \
  -F "Token=$TOKEN_OF_USER" \
  -X POST

上述指令,會回傳 JSON 結構如下:

{
  "ID": "11dVJp2kqop7X",
  "User": {
    "ID": "12UHuwvubMS2n",
    "Name": "JinmaAPI",
    "Picture": "https://pbs.twimg.com/profile_images/872802470677762048/hsmbLx4I_normal.png",
    "ThirdPartyID": "tw:3689630718",
    "Privacy": "1"
  },
  "Time": 1514210677.908,
  "Body": "Hello, Jinma",
  "Lat": 27.994401411046145,
  "Lng": -69.78515625,
  "SKF64": 1514210677.908,
  "App": {
    "ID": "167VMeshFbCnk",
    "Name": "Jinma API Tutorial",
    "Icon": "https://pbs.twimg.com/profile_images/872802470677762048/hsmbLx4I_400x400.png",
    "MarketingURI": "https://jinmaapi.github.io"
  }
}

/MsgDelete

刪除訊息。

HTTP 要求

POST https://www.jinma.io/MsgDelete

參數

參數 說明
MsgID 訊息 ID
Token 作者的 Token

範例

curl "https://www.jinma.io/MsgDelete" \
  -F "MsgID=11dVJp2kqop7X" \
  -F "Token=$TOKEN_OF_USER" \
  -X POST

上述指令,會直接回傳 HTTP 200 No Error。

GET 訊息

訊息中的 Time 值為 Unix 時間(自 1970/01/01 至今,以秒為單位)。

/MsgsByGeoAppUser

取得在給定的一個長方形地理區域裡,使用該應用程式,該使用者所發表的訊息。使用這個 API 來提供你的使用者或公開使用者的訊息。

HTTP 要求

GET https://www.jinma.io/MsgsByGeoAppUser

參數

參數 說明
CLat 中央點(緯度)
CLng 中央點(經度)
SLat 長方形尺寸(緯度)
SLng 長方形尺寸(經度)
AppID 應用程式 ID
UserID 使用者 ID
Token 使用者的 Token(非必要,假如是公開使用者)
SKF64 訊息排序的參數(非必要;用於分頁的參數;以秒為單位;未使用此參數,預設會回傳最新的訊息)

範例

curl -G "https://www.jinma.io/MsgsByGeoAppUser" \
  -d "CLat=29.649868677972304" \
  -d "CLng=-64.248046875" \
  -d "SLat=10.0" \
  -d "SLng=10.0" \
  -d "AppID=167VMeshFbCnk" \
  -d "UserID=12UHuwvubMS2n" \
  -d "Token=$TOKEN_OF_USER"

上述指令,會回傳 JSON 結構如下(預設狀況下,最新的訊息會排在前面):

{
  "Msgs": [{
      "ID": "11P52o14NXHEQ",
      "User": {
        "ID": "12UHuwvubMS2n",
        "Name": "JinmaAPI",
        "Picture": "https://pbs.twimg.com/profile_images/872802470677762048/hsmbLx4I_normal.png",
        "ThirdPartyID": "tw:3689630718",
        "Privacy": "1"
      },
      "Time": 1514211638.547,
      "Body": "Another message",
      "Lat": 29.649868677972304,
      "Lng": -64.248046875,
      "SKF64": 1514211638.547,
      "App": {
        "ID": "167VMeshFbCnk",
        "Name": "Jinma API Tutorial",
        "Icon": "https://pbs.twimg.com/profile_images/872802470677762048/hsmbLx4I_400x400.png",
        "MarketingURI": "https://jinmaapi.github.io"
      }
    },
    {
      "ID": "11TtpoJDzGaXH",
      "User": {
        "ID": "12UHuwvubMS2n",
        "Name": "JinmaAPI",
        "Picture": "https://pbs.twimg.com/profile_images/872802470677762048/hsmbLx4I_normal.png",
        "ThirdPartyID": "tw:3689630718",
        "Privacy": "1"
      },
      "Time": 1514211611.456,
      "Body": "Hello, Jinma",
      "Lat": 29.840643899834436,
      "Lng": -65.7421875,
      "SKF64": 1514211611.456,
      "App": {
        "ID": "167VMeshFbCnk",
        "Name": "Jinma API Tutorial",
        "Icon": "https://pbs.twimg.com/profile_images/872802470677762048/hsmbLx4I_400x400.png",
        "MarketingURI": "https://jinmaapi.github.io"
      }
    }
  ]
}

接著將參數 SKF64 設定為上例回傳最後一則訊息的 SKF64 值,來要求後續的訊息:

curl -G "https://www.jinma.io/MsgsByGeoAppUser" \
  -d "CLat=29.649868677972304" \
  -d "CLng=-64.248046875" \
  -d "SLat=10.0" \
  -d "SLng=10.0" \
  -d "AppID=167VMeshFbCnk" \
  -d "UserID=12UHuwvubMS2n" \
  -d "Token=$TOKEN_OF_USER" \
  -d "SKF64=1514211611.456"

/MsgsByGeoApp

取得在給定的一個長方形地理區域裡,使用該應用程式所發表的訊息。使用這個 API 來提供你的全部使用者所發表的訊息。

HTTP 要求

GET https://www.jinma.io/MsgsByGeoApp

參數

參數 說明
CLat 中央點(緯度)
CLng 中央點(經度)
SLat 長方形尺寸(緯度)
SLng 長方形尺寸(經度)
AppID 應用程式 ID
SKF64 訊息排序的參數(非必要;用於分頁的參數;以秒為單位;未使用此參數,預設會回傳最新的訊息)

範例

curl -G "https://www.jinma.io/MsgsByGeoApp" \
  -d "CLat=29.649868677972304" \
  -d "CLng=-64.248046875" \
  -d "SLat=10.0" \
  -d "SLng=10.0" \
  -d "AppID=167VMeshFbCnk"

上述指令,會回傳 JSON 結構如下(預設狀況下,最新的訊息會排在前面):

{
  "Msgs": [{
      "ID": "11BNtTswkGwMx",
      "User": {
        "ID": "12eFqKB2vkUWS",
        "Name": "denkeni",
        "Picture": "https://pbs.twimg.com/profile_images/595614938472718337/qmzDrkNJ_normal.jpg",
        "ThirdPartyID": "tw:945124819",
        "Privacy": "1"
      },
      "Time": 1514212144.318,
      "Body": "Message from another user",
      "Lat": 29.840643899834436,
      "Lng": -65.10498046875,
      "SKF64": 1514212144.318,
      "App": {
        "ID": "167VMeshFbCnk",
        "Name": "Jinma API Tutorial",
        "Icon": "https://pbs.twimg.com/profile_images/872802470677762048/hsmbLx4I_400x400.png",
        "MarketingURI": "https://jinmaapi.github.io"
      }
    },
    {
      "ID": "11TtpoJDzGaXH",
      "User": {
        "ID": "12UHuwvubMS2n",
        "Name": "JinmaAPI",
        "Picture": "https://pbs.twimg.com/profile_images/872802470677762048/hsmbLx4I_normal.png",
        "ThirdPartyID": "tw:3689630718",
        "Privacy": "1"
      },
      "Time": 1514211611.456,
      "Body": "Hello, Jinma",
      "Lat": 29.840643899834436,
      "Lng": -65.7421875,
      "SKF64": 1514211611.456,
      "App": {
        "ID": "167VMeshFbCnk",
        "Name": "Jinma API Tutorial",
        "Icon": "https://pbs.twimg.com/profile_images/872802470677762048/hsmbLx4I_400x400.png",
        "MarketingURI": "https://jinmaapi.github.io"
      }
    }
  ]
}

接著將參數 SKF64 設定為上例回傳最後一則訊息的 SKF64 值,來要求後續的訊息:

curl -G "https://www.jinma.io/MsgsByGeoApp" \
  -d "CLat=29.649868677972304" \
  -d "CLng=-64.248046875" \
  -d "SLat=10.0" \
  -d "SLng=10.0" \
  -d "AppID=167VMeshFbCnk" \
  -d "SKF64=1514211611.456"

/MsgsByGeo

取得在給定的一個長方形地理區域裡,所發表的訊息。你也許可以偶爾用用這個 API 不時探索地圖上的資料,但回傳訊息的規則隨時有可能會改變。

HTTP 要求

GET https://www.jinma.io/MsgsByGeo

參數

參數 說明
CLat 中央點(緯度)
CLng 中央點(經度)
SLat 長方形尺寸(緯度)
SLng 長方形尺寸(經度)
SKF64 訊息排序的參數(非必要;用於分頁的參數;以秒為單位;未使用此參數,預設會回傳最新的訊息)

範例

curl -G "https://www.jinma.io/MsgsByGeo" \
  -d "CLat=40.97595691909808" \
  -d "CLng=-75.58044433593754" \
  -d "SLat=17.566770639631663" \
  -d "SLng=111.181640625"

上述指令,會回傳 JSON 結構如下(預設狀況下,最新的訊息會排在前面):

{
  "Msgs": [{
      "ID": "11TtpoJDzGaXH",
      "User": {
        "ID": "12UHuwvubMS2n",
        "Name": "JinmaAPI",
        "Picture": "https://pbs.twimg.com/profile_images/872802470677762048/hsmbLx4I_normal.png",
        "ThirdPartyID": "tw:3689630718",
        "Privacy": "1"
      },
      "Time": 1514211611.456,
      "Body": "Hello, Jinma",
      "Lat": 29.840643899834436,
      "Lng": -65.7421875,
      "SKF64": 1514211611.456,
      "App": {
        "ID": "167VMeshFbCnk",
        "Name": "Jinma API Tutorial",
        "Icon": "https://pbs.twimg.com/profile_images/872802470677762048/hsmbLx4I_400x400.png",
        "MarketingURI": "https://jinmaapi.github.io"
      }
    },
    {
      "ID": "11LgkXp9y3Bt3",
      "User": {
        "ID": "12eFqKB2vkUWS",
        "Name": "denkeni",
        "Picture": "https://pbs.twimg.com/profile_images/595614938472718337/qmzDrkNJ_normal.jpg",
        "ThirdPartyID": "tw:945124819",
        "Privacy": "1"
      },
      "Time": 1478921183.484,
      "Body": "Message from another app",
      "Lat": 36.03133177633187,
      "Lng": -69.9609375,
      "SKF64": 1478921183.484,
      "App": {
        "ID": "163P7zum1xiRe",
        "Name": "Jinma API Tutorial (legacy)",
        "Icon": "",
        "MarketingURI": ""
      }
    }
  ]
}

接著將參數 SKF64 設定為上例回傳最後一則訊息的 SKF64 值,來要求後續的訊息:

curl -G "https://www.jinma.io/MsgsByGeo" \
  -d "CLat=40.97595691909808" \
  -d "CLng=-75.58044433593754" \
  -d "SLat=17.566770639631663" \
  -d "SLng=111.181640625" \
  -d "SKF64=1478921183.484"

/MsgByID

用 ID 取得訊息。

HTTP 要求

GET https://www.jinma.io/MsgByID

參數

參數 說明
ID 訊息的 ID
Token 使用者的 Token(非必要,假如是公開使用者)

範例

curl -G "https://www.jinma.io/MsgByID" \
  -d "ID=11TtpoJDzGaXH"

上述指令,會回傳 JSON 結構如下:

{
  "ID": "11TtpoJDzGaXH",
  "User": {
    "ID": "12UHuwvubMS2n",
    "Name": "JinmaAPI",
    "Picture": "https://pbs.twimg.com/profile_images/872802470677762048/hsmbLx4I_normal.png",
    "ThirdPartyID": "tw:3689630718",
    "Privacy": "0"
  },
  "Time": 1514211611.456,
  "Body": "Hello, Jinma",
  "Lat": 29.840643899834436,
  "Lng": -65.7421875,
  "SKF64": 1514211611.456,
  "App": {
    "ID": "167VMeshFbCnk",
    "Name": "Jinma API Tutorial",
    "Icon": "https://pbs.twimg.com/profile_images/872802470677762048/hsmbLx4I_400x400.png",
    "MarketingURI": "https://jinmaapi.github.io"
  }
}

錯誤處理

假如要求成功,Jinma API 會回傳 HTTP 200 No Error,並依據個別 API 可能回傳 JSON 字串。

假如要求失敗,Jinma API 會回傳對應的 HTTP 錯誤代碼,並回傳錯誤訊息的 JSON 物件結構如下:

"Error": {
  "Message": "$ERROR_MESSAGE"
}

或是回傳帶有 Error Code 的物件:

"Error": {
  "Code": "$ERROR_CODE",
  "Message": "$ERROR_MESSAGE"
}

以下是 Error Code 的列表:

Error Code 說明
Auth 使用者的 token 錯誤或已過期。你應該提示使用者重新登入。