Ver 0.1 (Alpha version, response in JSON format) HTTP interface

This version of API (Application Programming Interface) uses for sending request to web-service simple HTML form with method POST and answer in JSON format.

Status: active, Alpha version
Last edition: 2016-12-02
WEB protocol: HTTP
Authorization method: session cookies
Entry point: http://api.carinfo.kiev.ua

General section

Request form:

Quote:
<form action="http://api.carinfo.kiev.ua" method="post" id="form1">
<input name="Pversion" type="text" value="%s" />
<input name="user" type="text" value="%s" />
<input name="pass" type="text" />
<input name="mode" type="text" value="%s" />
<input name="reptype" type="text" value="%s" />
<input name="refid" type="text" value="%s" />
<input name="lang" type="text" value="%s" />
<input name="brand" type="text" value="%s" />
<input name="vinnumber" type="text" value="%s" />
<input type="submit" value="Send" />
</form>

Where input fields are:

  • Pversion - version of protocol used for processing this request (0.1); Obligatory parameter;
  • user - user's name on site (author of request); Obligatory parameter;
  • pass - user's password on site; Is used only during login;
  • mode - mode of request (check VIN, report of last activity, login and so on); Obligatory parameter;
  • reptype - variant of report; Obligatory parameter for mode = "report";
  • refid - user's defined identificator of request; Will be returned in answer without modification; Optional parameter;
  • lang - language of requested data; Obligatory parameter with mode = "check";
  • brand - brand of requested VIN for checking; Obligatory parameter with mode = "check";
  • vinnumber - regeuested VIN for checking; Obligatory parameter with mode = "check";

Answer (general structure):

Quote:

(
    [header] =>
        (
            ...
        )

[system_messages] =>
(
[system_news] =>
[news] =>
[personal_news] =>
[attention] =>
)

[data] =>
(
...
)

[messages] =>
)


Where output chapters are:



  • header - chapter with parameters of request and status code;
  • system_messages - reserved chapter;
  • data - chapter with a "body" of answer; its content depends on the type of request;
  • messages - reserved chapter;

    Typical workflow


    Login in web-service:


    Quote:
    <form action="http://api.carinfo.kiev.ua" method="post" id="form1">

    <input name="Pversion" type="text" value="0.1" />

    <input name="user" type="text" value="myusername" />

    <input name="pass" type="text" value="mypassword" />

    <input name="mode" type="text" value="login" />

    <input name="refid" type="text" value="-1" />

    </form>


    Answer from web-service:


    Success:

    Quote:


    (
    [header] =>
    (
    [response_code] =>
    (
    [200] => You are welcome, myusername!
    )

    [user] => myusername
    [uid] => 2
    [Pversion] => 0.1
    [mode] => login
    [refid] => -1
    )

    )


    Fail:

    Quote:


    (
    [header] =>
    (
    [response_code] =>
    (
    [403] => Invalid user myusername or password
    )

    [Pversion] => 0.1
    [mode] => login
    [refid] => -1
    )

    )


    With this answer your application will get session cookies, which must be send with any request to web-service. Usually lifetime of cookies is measured by the weeks. If cookies become invalid answer from web-service on any request will be like this:

    Quote:


    (
    [header] =>
    (
    [response_code] =>
    (
    [403] => Access denied. Please login
    )

    [Pversion] => 0.1
    [refid] => -1
    )

    )


    With this answer you must login again.


    Checking the VIN


    Request form:


    Quote:
    <form action="http://api.carinfo.kiev.ua" method="post" id="form1">

    <input name="Pversion" type="text" value="0.1" />

    <input name="user" type="text" value="myusername" />

    <input name="mode" type="text" value="check" />

    <input name="refid" type="text" value="1480700056" />

    <input name="lang" type="text" value="en" />

    <input name="brand" type="text" value="mercedes-benz" />

    <input name="vinnumber" type="text" value="WDB1240191J016310" />

    <input type="submit" value="Send" />

    </form>


    Where input fields are:



    • Pversion - version of protocol used for processing this request (0.1); Obligatory parameter;
    • user - user's name on site (author of request); Obligatory parameter;
    • mode - mode of request; here it's "check";
    • refid - user's defined identificator of request; Will be returned in answer without modification; Optional parameter;
    • lang - language of requested data; parameter is case sensitive;
    • brand - brand of requested VIN for checking; parameter is case insensitive; in answer brand will be converted to upper case;
    • vinnumber - regeuested VIN for checking;

    Chapter "data" in answer has a structure, fully identical to usual online page: It's an array of names of tables, and each of them is an array of fields in it. Answer for this request will be the next:


    Quote:


    (
    [header] =>
    (
    [brand] => MERCEDES-BENZ
    [vinnumber] => WDB1240191J016310
    [lang] => en
    [response_code] =>
    (
    [200] => Ok. See section 'data' in root of answer object.
    )

    [Pversion] => 0.1
    [mode] => check
    [refid] => 1480700056
    )

    [system_messages] =>
    (
    [system_news] =>
    [news] =>
    [personal_news] =>
    [attention] =>
    )

    [data] =>
    (
    [system_messages] => Array
    (
    [0] => 200
    [1] => Warning: check digit is not correct
    )

    [Main data] =>
    (
    [Ident. number (FIN)] => WDB1240191J016310
    [Baumuster] => 124019
    [Sales name] => E200
    [Cabin] => 00000
    [Permanent link] => http://carinfo.kiev.ua/node/451?su=cab49hl_
    [Order number] => 0 3 543 13456 (Destination: Italy)
    [Delivery date] => 1993-06
    [PAINT1] => 199
    [Interior color] => 001
    [Engine] => 111940 10 025857
    [Gearbox] => 717413 06 360118
    [Lights units] => HELLA
    [Wipers] => BOSCH 930701
    [Class] => 1
    )

    [SA codes] =>
    (
    [001A] => No code designation available
    [199] => APPLICATION CODE FOR COMPONENT PROCESSING
    [240] => OUTSIDE TEMPERATURE INDICATOR
    [260] => TYPE DESTINATION ON TRUNK LID - ELIMINATION
    [305] => DUST FILTER
    [341] => ADDITIONAL BLINKER LAMPS
    [430] => HEADREST IN THE REAR, LEFT AND RIGHT
    [524] => PAINTWORK - PRESERVATION
    [570] => FOLDING ARMREST, FRONT
    [587] => No code designation available
    [593] => ALL-ROUND WD-GREEN GLASS,HEATED REAR WINDOW-ESG,BF
    [620] => AIR POLLUTION CONTROL
    [630] => ECE - WARNING TRIANGLE
    [731] => WOOD TRIM BURRED WALNUT ROOT
    [859] => No code designation available
    [877] => No code designation available
    [916] => FUEL TANK WITH INCREASED CONTENT
    )

    [SA numbers] =>
    (
    [01] => 01 12400/04/ 01 12412/21/ 01 12439/13/
    [03] => 03 12400/04/ 03 12412/21/
    [07] => 07 12412/21/
    [09] => 09 12412/21/
    [13] => 13 12328/61/ 13 12412/21/
    [14] => 14 12328/61/ 14 12400/04/ 14 12439/13/
    [15] => 15 12328/61/ 15 12400/04/ 15 12412/21/ 15 12439/13/
    [18] => 18 12412/21/
    [20] => 20 12328/61/ 20 12412/21/
    [22] => 22 12412/21/
    [47] => 47 11131/53/ 47 11132/65/
    [49] => 49 11192/51/
    [52] => 52 11047/07/
    [54] => 54 11163/64/ 54 11283/08/ 54 11294/16/ 54 11302/06/ 54 11320/07/ 54 11372/74/
    [58] => 58 11235/03/ 58 11372/74/
    [62] => 62 56103/62/ 62 56106/24/ 62 56517/02/ 62 56795/14/ 62 56795/25/ 62 56795/36/ 62 56795/53/
    [67] => 67 56512/06/ 67 56515/01/ 67 56517/02/
    [68] => 68 56103/62/ 68 56881/01/
    [69] => 69 56125/06/
    [72] => 72 56512/06/ 72 56515/01/ 72 56638/50/ 72 56795/14/ 72 56795/25/ 72 56795/36/ 72 56795/53/ 72 56881/01/ 72 56907/01/ 72 56908/77/ 72 56908/78/ 72 57168/14/ 72 57168/26/
    [73] => 73 56512/06/ 73 56515/01/ 73 56881/01/ 73 56907/01/ 73 56915/29/
    [74] => 74 56512/06/ 74 56638/50/
    [75] => 75 56638/50/ 75 56795/14/ 75 56795/25/ 75 56795/36/ 75 56795/53/
    [79] => 79 56512/06/
    [80] => 80 56103/62/ 80 56128/11/ 80 56517/02/ 80 56523/01/ 80 56644/13/ 80 56812/09/
    [82] => 82 11283/08/ 82 11374/01/ 82 11377/01/ 82 56103/62/ 82 56106/24/ 82 56125/06/ 82 56313/06/ 82 56494/04/ 82 56515/01/ 82 56517/02/ 82 56523/01/
    [83] => 83 56106/24/ 83 56128/11/ 83 56517/02/ 83 57237/10/
    [88] => 88 56103/62/ 88 56313/06/ 88 56494/04/ 88 56579/18/ 88 56795/14/ 88 56795/25/ 88 56795/36/ 88 56795/53/
    [89] => 89 56638/50/
    [91] => 91 56681/07/
    [92] => 92 56523/01/
    [98] => 98 56103/62/
    )

    [System information] =>
    (
    [Data language] => en
    [Record was added in database] => 2013-09-08 14:03
    [Last query date] => 2016-12-02 23:32
    [Manufacturer's data version] => DW 09/2013 Delta 1 from 2013-09-02
    [DB storage version] => 1.0
    [Data display version] => 2.2
    [Brand] => Mercedes-Benz
    )

    )

    [messages] =>
    )


    For better understanding of structure of answer you can compare it with online page, which is placed in way [data]->[Main data]->[Permanent link].


    Other service functions


    Available brands and languages for requesting


    Request form:


    Quote:
    <form action="http://api.carinfo.kiev.ua" method="post" id="form1">

    <input name="Pversion" type="text" value="0.1" />

    <input name="user" type="text" value="myusername" />

    <input name="mode" type="text" value="report" />

    <input name="reptype" type="text" value="modules" />

    <input name="refid" type="text" value="a125fg" />

    <input type="submit" value="Send" />

    </form>


    Answer


    Quote:


    (
    [header] =>
    (
    [reptype] => modules
    [response_code] =>
    (
    [200] => Ok
    )

    [Pversion] => 0.1
    [mode] => report
    [refid] => a125fg
    )

    [data] =>
    (
    [byBrand] =>
    (
    [BMW] =>
    (
    [0] => ru
    [1] => en
    [2] => fr
    [3] => de
    [4] => es
    [5] => pt
    )

    [BMW MOTORRAD] => Array
    (
    [0] => ru
    [1] => en
    [2] => fr
    [3] => de
    [4] => es
    [5] => pt
    )

    ...

    )

    [byLang] =>
    (
    [ru] =>
    (
    [0] => BMW
    [1] => BMW MOTORRAD
    [2] => CITROEN
    ...
    )

    [en] => Array
    (
    [0] => BMW
    [1] => BMW MOTORRAD
    [2] => CHRYSLER
    ...
    )

    ...

    )

    )

    )


    Last requests


    Request form:


    Quote:
    <form action="http://api.carinfo.kiev.ua" method="post" id="form1">

    <input name="Pversion" type="text" value="0.1" />

    <input name="user" type="text" value="myusername" />

    <input name="mode" type="text" value="report" />

    <input name="reptype" type="text" value="accesslog" />

    <input name="refid" type="text" value="dada11156" />

    <input type="submit" value="Send" />

    </form>


    Answer:


    Quote:


    (
    [header] =>
    (
    [reptype] => accesslog
    [response_code] =>
    (
    [200] => Ok
    )

    [Pversion] => 0.1
    [mode] => report
    [refid] => dada11156
    )

    [data] =>
    (
    [1] =>
    (
    [brand] => BMW
    [vin] => WBADP71050GS76523
    [datetime] => 2016-12-04 11:01:52 +0300
    [lang] => en
    )

    [2] =>
    (
    [brand] => RENAULT
    [vin] => VF1JZ090347945106
    [datetime] => 2016-12-04 11:00:13 +0300
    [lang] => en
    )

    [3] =>
    (
    [brand] => RENAULT
    [vin] => VF1BB0FBF24659201
    [datetime] => 2016-12-04 10:59:42 +0300
    [lang] => en
    )
    ....

    )

    )


    Where parameter [datetime] - it's a time of request with time zone settings in user's profile on site. Relative offset to UTC (GMT) is added at the end.


Post new comment

  • Allowed HTML tags: <a> <em> <strong> <cite> <code> <ul> <ol> <li> <dl> <dt> <dd>
  • Lines and paragraphs break automatically.
  • You can use BBCode tags in the text.
  • Textual smileys will be replaced with graphical ones.

More information about formatting options

CAPTCHA
This question is for testing whether you are a human visitor and to prevent automated spam submissions.