Keyboard Part Number Database External Access

Version 1.5

The Keyboard Part Number Database supports external access so that your website or application can pull data on a particular keyboard or multiple keyboards in a standardised format. This page will detail how to make a request for such data and what format(s) the data will be provided in.

Please note that this is not an absolute guaranteed service - this service will run so long as there is no abuse of it and I have the funds to maintain the traffic it generates. As such, I reserve the right to discontinue the external access service as I please but I will strive to ensure there is at least a two-week notice of such action.

Constructing a request

The API can be utilised by accessing the request URL https://sharktastica.co.uk/kb_db_req.php with some GET parametres. All requests will need to have at least three parametres to form a URL that looks like https://sharktastica.co.uk/kb_db_req.php?param1=x&param2=y&param3=z, which are all explained below.

Version

The ver parametre is a (technically) optional variable used for confirming if your request was made with the current version of the API in mind. If the variable isn't given, the request is accepted but a message is returned advising the author to use it. If there's a version mismatch, the request is accepted (provided there isn't any other error) but a message is returned advising the author that the result may not be what their code expects.

ver=1.5

Match field

Match field is the first of two methods of searching for a result and thus a choice variable that can be used instead of search query. This parametre doesn't have a set name. Instead, it's used by specifying one of the field names and assigning it your search query. See the "Possible fields" table below to find out what fields you can use.

pn=1391401

Search query (q)

Search query is the second of two methods of searching for a result and thus a choice variable that can be used instead of match field. The q parametre is used to denote this. See the "Search query guide" below to find out how to form the queries to input into it.

q=!IBM Enhanced Keyboard

Data type (dat)

The dat parametre is a required variable that specifies that the returned data format should be. At present, the supported data formats are JSON (stable) and XML (beta).

dat=JSON

Fields list (fields)

The fields parametre is a required variable that specifies what fields of data you want returned. See the "Possible fields" table below to find out what fields you can use. You can use one or more of the field names as a comma-separated list, or, you can use the '*' wildcard to indicate you want all fields.

fields=name,type,date,oem,branding

Row count limit (c)

The c parametre is an optional variable used for specifying a results count limit for your results.

c=5

Handling the output

Every single request made should return a result in either JSON or XML as per your dat parametre or JSON if no dat is specified. Below outlines all the possible members to expect.

License string

The license member is an always-present value indicates gives the license (a URL to more information on it) used for original data in the ASK Keyboard Part Number Database.

"license": "https://creativecommons.org/licenses/by-nc-sa/4.0/"

Success flag boolean

The success member is an always-present value that indicates if a request was successful (true) or resulted in error (false). Note that a request that produced no results due to lack of matches (and not due to error) is still considered a successful request.

"success": true

Error message string

The message member is a success-dependent value that contains any error messages returned from attempting the request. The member will only be present if the request was unsuccessful. Note that at present, all unsuccessful requests are returned in JSON regardless of whether XML use has been flagged by a dat parametre.

"message": "No fields parametre provided! Please refer to https://sharktastica.co.uk/kb_db_api.php for help with using the Keyboard Part Number Database External Access API."

Results count integer

The hits member is a success-dependent value that indicates how many results were found with your request regardless of what row count limit was provided. If the request is a match field request, the value will always be 1 if a keyboard is found. For all types of request, 0 indicates no results found. The member will only be present if the request was successful.

"hits": 42

Results data array

The results array is a success-dependent value that contains an array of all keyboard data found. If the request is a match field request, the array will only contain one element if a keyboard is found. If no results are found by an request, the array will still exist but will be empty. The member will only be present if the request was successful.

"results": [
 {
  "pn": "1391401",
  "date": "1987 Q2"
 }
]

Possible fields

Fixed fields

These fields are returned to matter what the user requests.

Optional fields

These field names are used for specifying a search parametre or for filtering what fields of data should be returned. Fields correspond to specific data on keyboards, which is explained in the key below.

Search query guide

If you decide to use search queries instead of match field, note that there are three types of searches you can pull off with the q parametre. These are the same as the latter three searching strategies outlined in the Keyboard Part Number Database FAQ page for use with the website's public database interface. If you plan to allow users of your website or application to search via this request API, it might be prudent to link them to that help page or write a version of it for your website or application.

Exact single-term searching

If you want something very specific, putting an exclamation mark before your query will flag that you want an exact match. In the example below, this will return all the keyboards that have a field that exactly reads "Model F Functional Key Keyboard".

q=!Model F Functional Key Keyboard

Additive multiple-term searching

If you want many results without exact matching and have them sorted about the amount of occurrences of each term in each result, comma-separate the terms. In the example below, this will return all keyboards that have a fields reading "IBM", "Model F" or "122" sorted by the ascending total number of occurrences found.

q=IBM,Model F,122

Subtractive multiple-term searching

If you want very refined results without exact matching, semi-colon separate the terms. In the example below, this will return all keyboards that have fields reading "IBM", "Model F" and "122" at the same time sorted by part number.

q=!IBM;Model F;122

Examples

Successful JSON single-result match field request

kb_db_req.php?ver=1.5&pn=1391401&dat=JSON&fields=name,type,date,oem,branding

{
 "version": 1.5,
 "license": "https://creativecommons.org/licenses/by-nc-sa/4.0/",
 "success": true,
 "hits": 1,
 "results": [
  {
   "pn": "1391401",
   "name": "IBM Enhanced Keyboard",
   "type": "Model M Enhanced PC Keyboard",
   "date": "1987 Q2",
   "oem": "IBM US, Lexmark",
   "branding": "IBM grey oval, IBM blue oval"
  }
 ]
}

Successful JSON multiple-result search query request

kb_db_req.php?ver=1.5&q=!IBM Enhanced Keyboard&dat=JSON&fields=name,type,date,layout&c=3

{
 "version": 1.5,
 "license": "https://creativecommons.org/licenses/by-nc-sa/4.0/",
 "success": true,
 "hits": 22,
 "results": [
  {
   "pn": "1391401",
   "name": "IBM Enhanced Keyboard",
   "type": "Model M Enhanced PC Keyboard",
   "date": "1987 Q2",
   "layout": "US ANSI"
  },
  {
   "pn": "1391402",
   "name": "IBM Enhanced Keyboard",
   "type": "Model M Enhanced PC Keyboard",
   "date": "1987 Q2",
   "layout": "French AZERTY ISO"
  },
  {
   "pn": "1391403",
   "name": "IBM Enhanced Keyboard",
   "type": "Model M Enhanced PC Keyboard",
   "date": "1987 Q2",
   "layout": "German ISO"
  }
 ]
}

Success JSON request with no results found

kb_db_req.php?ver=1.5&pn=999999999&dat=JSON&fields=*

{
 "version": 1.5,
 "license": "https://creativecommons.org/licenses/by-nc-sa/4.0/",
 "success": true,
 "hits": 0,
 "results": []
}

Error with request

kb_db_req.php

{
 "version": 1.5,
 "license": "https://creativecommons.org/licenses/by-nc-sa/4.0/",
 "success": false,
 "message": "No GET parametres provided! Please refer to https://sharktastica.co.uk/kb_db_api.php for help with using the Keyboard Part Number Database External Access API."
}