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:

• http://tirtayasa.azurewebsites.net/handle.php (testing, unstable) (no longer supported)
• http://kiri.travel/handle.php (production, recommended but be nice please)

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:

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:

The KIRI API service responds with the following format:

#!javascript

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

• http://kiri.travel/images/means/[means]/[means_details].png
• http://kiri.travel/images/means/[means]/baloon/[means_details].png

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:

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:

#!javascript

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

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:

• http://kiri.travel/images/means/[means]/[means_details].png
• http://kiri.travel/images/means/[means]/baloon/[means_details].png
• http://kiri.travel/images/means/[means]/mobile/[means_details].png

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:

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.