Permalink
Find file Copy path
Fetching contributors…
Cannot retrieve contributors at this time
621 lines (482 sloc) 16.3 KB

Jinma API Documentation

Table of Contents

Introduction

With Jinma API, building a location-based service is fast and easy.

Every message posted on Jinma will be publicly available and the service is free of charge. Just that simple.

Create your apps

Create an app for every use case, for example, FatasticWeather app for showing open data of weather, FoodNote app for users keeping food notes.

If you are the only data provider, simply follow the steps below, and get your access token directly with web browser. No need to implement user login UIs. Great!

If you would like other users to provide data, since Jinma follows OAuth 2.0 protocol, so your app can do things on behalf of your users on Jinma platform.

Create an app

Login and create an app on Jinma here. The App ID ($APP_ID) and Redirect URI ($REDIRECT_URI) are required for OAuth 2 flow.

OAuth 2 flow

  1. Present the auth webpage to the user: https://www.jinma.io/OAuth2Auth?ClientID=$APP_ID&RedirectURI=$REDIRECT_URI For mobile apps, use in-app browser tab, such as SFSafariViewController on iOS, and Custom Tabs on Android. Notice: You should not use in-app webview to present this /OAuth2Auth page. Read more on OAuth 2.0 for Native Apps.

  2. The redirected URI will come with Code parameter. You should use https://www.jinma.io/OAuth2Token?ClientID=$APP_ID&Code=$CODE) to verify the code and finally get the user 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"

User

/Me

Get user ID and profile picture.

Notice that you can convert ThirdPartyID into social network profile weblink, where Twitter account starts with tw: and Facebook account starts with fb:.

Language value is the user's language preference across login process, and will be used for Jinma webpages like user settings. You may use it for client app language, too.

HTTP Request

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

Query Parameters

Parameter Description
Token Token of user

Example

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

The above command returns JSON structured like this:

{
  "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"
  }
}

Publicity

All messages created on Jinma are publicly available.

However, we understand that accessing to all messages across the map for a specific user can be a serious privacy issue. So, APIs for getting messages of a specific user (ex./MsgsByGeo*User) would be only available with the user's access token, by default.

In other words, only after the user authorizes your app, so you are able to serve specifically his/her messages.

On the contrary, if your account aims to provide only public open data, not privacy-related, you can switch your account into Public account in user settings page, so APIs for getting messages of your account would be available without your access token! That is, for everyone's use! Yeah!

POST message

/MsgCreate

Create a message at given geolocation.

HTTP Request

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

Query Parameters

Parameter Description
Lat Latitude
Lng Longitude
Body Body of message
Token Token of user

Example

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

The above command returns JSON structured like this:

{
  "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"
  }
}

Notice: /MsgsBy*** may not immediately return new messages just created with /MsgCreate. To show immediate result of /MsgCreate on the app UI, consider adding the returning message object on it.

/MsgUpdate

Update/Edit the message.

HTTP Request

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

Query Parameters

Parameter Description
MsgID Message ID
Body Body of edited message
Token Token of author

Example

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

The above command returns JSON structured like this:

{
  "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

Delete the message.

HTTP Request

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

Query Parameters

Parameter Description
MsgID Message ID
Token Token of author

Example

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

The above command would just return HTTP 200 No Error.

GET messages

In a message, Time value is Unix time, time since 1970/01/01 in seconds.

/MsgsByGeoAppUser

Get messages within any rectangle around a location, specifically created with given app and by the user. Use this API to serve your user's or public users' messages.

HTTP Request

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

Query Parameters

Parameter Description
CLat Center point (Latitude)
CLng Center point (Longitude)
SLat Size of rectangle (Latitude)
SLng Size of rectangle (Longitude)
AppID App ID
UserID User ID
Token Token of the user (optional if the user is public)
SKF64 parameter for message sorting (optional, the parameter for pagination; request without this parameter will return the latest messages by default.)

Example

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"

The above command returns JSON structured like this (latest message comes first by default):

{
  "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"
      }
    }
  ]
}

Then request the following messages with parameter SKF64 set to SKF64 of the last message, for the above example:

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

Get messages within any rectangle around a location, specifically created with given app. Use this API to serve messages from all your users.

HTTP Request

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

Query Parameters

Parameter Description
CLat Center point (Latitude)
CLng Center point (Longitude)
SLat Size of rectangle (Latitude)
SLng Size of rectangle (Longitude)
AppID App ID
SKF64 parameter for message sorting (optional, the parameter for pagination; request without this parameter will return the latest messages by default.)

Example

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"

The above command returns JSON structured like this (latest message comes first by default):

{
  "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"
      }
    }
  ]
}

Then request the following messages with parameter SKF64 set to SKF64 of the last message, for the above example:

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

Get messages within any rectangle around a location, like in a public square. You may use this API to explore data around occasionally, but the rules of returning messages may be subject to change.

HTTP Request

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

Query Parameters

Parameter Description
CLat Center point (Latitude)
CLng Center point (Longitude)
SLat Size of rectangle (Latitude)
SLng Size of rectangle (Longitude)
SKF64 parameter for message sorting (optional, the parameter for pagination; request without this parameter will return the latest messages by default.)

Example

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

The above command returns JSON structured like this (latest message comes first by default):

{
  "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": ""
      }
    }
  ]
}

Then request the following messages with parameter SKF64 set to SKF64 of the last message, for the above example:

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

Get the message with its ID.

HTTP Request

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

Query Parameters

Parameter Description
ID ID of the message
Token Token of the user (optional if the user is public)

Example

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

The above command returns JSON structured like this:

{
  "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"
  }
}

Error handling

If success, Jinma API will return HTTP 200 No Error, with or without result JSON string depending on the requested API.

If failed, Jinma API will return corresponding HTTP error code, with an error message JSON object structured as:

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

or with error code:

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

Here is a list of error code:

Error Code Description
Auth User token error or expired. You should alert user to log in again.