Wiki

Clone wiki

KIRI_API / KIRI API v2 Documentation

Introduction

KIRI API can be accessed in several ways, described in the following subsections. All requests must contain API key, which can be retrieved through the KIRI API Management Dashboard (or click here to go directly to the dashboard).

API Specifications

Web Service

All web service requests should be sent as POST message (as in <form method="POST">) or GET request to one of the following URL:

Parameters are passed in the POST/GET parameters, with the mandatory parameter being “mode” parameter, to determine which service is requested. This parameter and the rest will be explained in the following subsections.

Returned values are formatted in JSON, with guarantee of minimum two variables:

Variable Possible values Description
status “ok” or “error” Determines whether the request was performed successfully or not.
message Text string (exists when status is “error”) Explains the specific cause of the error.

Some requests requires API key provided by KIRI API team (in the future it will be auto-generated when you log in to our system).

Routing Web Service

To perform routing request, you need to provide the following parameters:

Parameter Valid values Description
version 2 Tell service to use version 2 protocol
mode “findroute” Instruct service to find the route
locale “en” or “id” The language to be used for response
start lat,lng (both are decimal values) Latitude and longitude of the start point
finish lat,lng (both are decimal values) Latitude and longitude of the finish point
presentation “mobile” or “desktop” Determines presentation type for the result. For example, if presentation is mobile, a "tel:" link will be added to the step result.
apikey 16-digit hexadecimals Your API key

The KIRI API service responds with the following format:

{
    "status": "ok" or "error"
    "routingresults": [
        {
            "steps": [
                [
                    "walk" or "none" or others,
                    "walk" or vehicle_id or "none",
                    ["lat_1,lon_1", "lan_2,lon_2", ... "lat_n,lon_n"],
                    "human readable description, dependent on locale",
                    URL for ticket booking or null,
                    URL for route editor or null,
                ],
                [
                    "walk" or "none" or others,
                    "walk" or vehicle_id or "none",
                    ["lat_1,lon_1", "lan_2,lon_2", ... "lat_n,lon_n"],
                    "human readable description, dependent on locale",
                    URL for ticket booking or null,
                    URL for route editor or null,
                ]
            ],
            "traveltime": any text string, null if and only if route is not found.
        },
        {
            "steps": [ ... ],
            "traveltime": "..."
        },
        {
            "steps": [ ... ],
            "traveltime": "..."
        },
        ...     
    ]
}

When findroute request is successful, the server must also return the routing result, which is an array of steps, each containing the description in the format of another array:

  • Index 0 contains the means, either "walk", "none" (route not found), or others for vehicle
  • Index 1 contains the means detail:
    • If the means was "walk", then this field must be "walk"
    • If the means was "none", then this field must be "none"
    • Otherwise, then this field contains the vehicle id, which can be used to decide which picture to show .
  • Index 2 is another array of string, containing the path in "lat,lon" format. When the means is "none", it contains exactly two elements, that is the start and finish point.
  • Index 3 is the human readable form of those information, to be shown to the user. This field is dependant on the locale parameter provided at the request. This information may contain the following token:
    • %fromicon = a placeholder for showing the "from" icon, especially in mobile mode presentation
    • %toicon = a placeholder for showing the "to" icon, especially in mobile mode presentation
  • Index 4 contains the URL for ticket booking, if available. Otherwise it would be null.
  • Index 5 contains the URL for route editor, if available. Otherwise it would be null.

Note that KIRI provides three types of image bank that can be accessed through the following URL:

Where [means] can retrieved from index 0 of return value, and [means_details] can be retrieved from index 1. For example, here's the URL for baloon image of angkot cicaheumledeng: http://kiri.travel/images/means/angkot/baloon/cicaheumledeng.png

Search Place Web Service

The “Routing Web Service” finds the route based upon lat,lng coordinate, which is inconvenient for end users. This service helps to “convert” text string to lat,lng. Note that this request is usually passed again to a third party provider. However using this service guarantees the same result as it is in http://kiri.travel. To perform routing request, you need to provide the following parameters:

Parameter Valid values Description
version 2 Tell the server to use protocol version 2
mode "searchplace" Instruct service to perform place search.
region cgk, bdo, mlg, or sub lowercased IATA Airport Code of the city to search places
querystring any text string at least 1 character The query string to be searched using the service. It may be appended with ", <region-name>" to alter the region.
apikey 16-digit hexadecimals Your API key

When findroute request is successful, the server must also return the routing result, which is an array of steps, each containing the description in the format of another array:

{
    "status": "ok" or "error"
    "searchresult": [
        {
            "placename": "place name"
            "location": "lat,lon"
        },
        {
            "placename": "place name"
            "location": "lat,lon"
        },
        ...
    ]
    "attributions": [
        "attribution_1", "attribution_2", ...
    ]
}

When findplace request is successful, the server must also return the placeresult, which is an array of steps, each containing the description in the format of mapping:

  • searchresult -> contains array of result objects:
    • placename: the place name
    • location: latitude, longitude of the place
  • attributions -> contains array of string, additional attribution to show

Nearest Transports Web Service

You can request KIRI API to show nearest transports around a particular point. To do that, you need to use the following request:

Parameter Valid values Description
version 2 Tell service to use version 2 protocol
mode "nearbytransports" Instruct the service to find available transport around a point.
start lat,lng (both are decimal values) Latitude and longitude of the point to search
apikey 16-digit hexadecimals Your API key

The response of that request is as follow:

{
    "status" : "ok" or "error",
    "nearbytransports" : [
        [
            "bdo_angkot",
            "cisitutegallega",
            "Cisitu - Tegallega",
            "0.120"
        ], [
            "bdo_angkot",
            "sthalllembang",
            "St. Hall - Lembang",
            "0.120"
        ], ...
    ]
}

When the nearby transports request is successful, the response contains array of nearby transports, formatted as above, with each transport is an array of size for with the following specifications:

  • Index 0 contains the means
  • Index 1 contains the means detail:
  • Index 2 contains the human readable vehicle name
  • Index 3 is the distance in kilometer from start point

The result will be sorted in ascending order based on its distance.

Note that KIRI provides three types of image bank that can be accessed through the following URL:

KIRI Widget

KIRI Widget documentation is available on a separate page KIRI Widget Documentation specially written for people who don't code.

It is a way to quickly embed a KIRI map and direction into an html using iframe tag.

URL Linking “Smart Direction”

Smart Direction works simply by asking the user’s browser to navigate to certain URL. The URL to navigate is as follow: http://kiri.travel?start=start&finish=finish&locale=locale

The parameters are explained below:

Parameter Valid values Description
start Query string or lat,lng Text query of a place to search or latitude,longitude (in decimal) as start point
finish Query string or lat,lng Text query of a place to search or latitude,longitude (in decimal) as finish point
locale (optional) “en” or “id” Forcing the user preference locale (language).

Example of URL can be retrieved by performing a search in http://kiri.travel and clicking the “Get Link” button.

At the moment this type of API is free for use, and apikey is not required.

Updated