API Documentation

Usage

API use is limited to 25 per month on the free plan. Attempted calls after the free limit will return a 429 - Too many requests response. Subscribe to one of our pricing options for increased usage.

Try It Out

Response

Loading...

                      

GET Request

curl -XGET 'https://homespy.io/api/decode?api_token=X1EuyvggI26JpKJ4KzAFWTMh8sBtxV86e5ACK6kE4Zj3lIRBgvMJsjYTwq8B&make=GE&serial=DZ153000G&model=GHWN4250DOWW'

POST Request

curl -XPOST -H 'Accept: Accept : application/json' -H 'Authorization: Bearer X1EuyvggI26JpKJ4KzAFWTMh8sBtxV86e5ACK6kE4Zj3lIRBgvMJsjYTwq8B' -H "Content-type: application/json" -d '{"make" : "GE", "serial" : "DZ153000G", "model" : "GHWN4250DOWW"}' 'https://homespy.io/api/decode'
$ch = curl_init(); curl_setopt($ch, CURLOPT_URL, 'https://homespy.io/api/decode'); curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1); curl_setopt($ch, CURLOPT_POST, 1); curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode(["make" => "GE", "serial" => "DZ153000G", "model" => "GHWN4250DOWW"]); $headers = array(); $headers[] = "Authorization" => "Bearer X1EuyvggI26JpKJ4KzAFWTMh8sBtxV86e5ACK6kE4Zj3lIRBgvMJsjYTwq8B"; $headers[] = "Accept" => "application/json"; $headers[] = "Content-Type" => "application/json"; curl_setopt($ch, CURLOPT_HTTPHEADER, json_encode($headers)); $result = curl_exec($ch); if (curl_errno($ch)) { echo 'Error:' . curl_error($ch); } curl_close($ch);
fetch('https://homespy.io/api/decode', { method: 'POST', headers: { 'Accept': 'Accept : application/json', 'Authorization': 'Bearer X1EuyvggI26JpKJ4KzAFWTMh8sBtxV86e5ACK6kE4Zj3lIRBgvMJsjYTwq8B', 'Content-type': 'application/json' }, // body: '{"make" : "GE", "serial" : "DZ153000G", "model" : "GHWN4250DOWW"}', body: JSON.stringify({ 'make': 'GE', 'serial': 'DZ153000G', 'model': 'GHWN4250DOWW' }) });
using System.Net.Http; using System.Net.Http.Headers; HttpClient client = new HttpClient(); HttpRequestMessage request = new HttpRequestMessage(HttpMethod.Post, "https://homespy.io/api/decode"); request.Headers.Add("Accept", "Accept : application/json"); request.Headers.Add("Authorization", "Bearer X1EuyvggI26JpKJ4KzAFWTMh8sBtxV86e5ACK6kE4Zj3lIRBgvMJsjYTwq8B"); request.Content = new StringContent("{\"make\" : \"GE\", \"serial\" : \"DZ153000G\", \"model\" : \"GHWN4250DOWW\"}"); request.Content.Headers.ContentType = new MediaTypeHeaderValue("application/json"); HttpResponseMessage response = await client.SendAsync(request); response.EnsureSuccessStatusCode(); string responseBody = await response.Content.ReadAsStringAsync();

Authentication

Credentials and body are passed in the same call to the below endpoint.

GET/POST https://homespy.io/api/decode

Credentials consist of your api token only. It can be sent in the headers with as a bearer token, as part of form data or appended to the request url.

https://homespy.io/api/decode?api_token=X1EuyvggI26JpKJ4KzAFWTMh8sBtxV86e5ACK6kE4Zj3lIRBgvMJsjYTwq8B headers: { "Content-Type" : "application/json", "Authorization" : "Bearer X1EuyvggI26JpKJ4KzAFWTMh8sBtxV86e5ACK6kE4Zj3lIRBgvMJsjYTwq8B" } 'headers' => [ 'Authorization' => 'Bearer X1EuyvggI26JpKJ4KzAFWTMh8sBtxV86e5ACK6kE4Zj3lIRBgvMJsjYTwq8B', 'Accept' => 'application/json', ]

An example of a failed 401 failed authentication response.

{
  "message": "Unauthenticated."
}

Request Parameters

Basic Request: https://homespy.io/api/decode?api_token={your_api_token}&make={make}&serial={serialNumber}&model={modelNumber}

serial - String, any length model - String, any length make - Option within list below * We will format make values for consistency. Whirlpool, Whirl Pool and whirlpool will all format to WHIRLPOOL. AOSMITH ADMIRAL ALLIANCE AMANA AMERICANSTANDARD AMERICANA ASKO BOSCH BRADFORDWHITE BRAVOS BRYANT CABRIO CAFE CALORIC CARRIER COLEMAN COMFORTMAKER CONQUEST COOLERATOR CROSLEY CRYSTALTIPS DACOR DANBY DUCANE ELECTROLUX ESTATE FIRSTCO FISHERANDPAYKEL FRIGIDAIRE GE GAGGENAU GIBSON GLENWOOD GOODMAN HAIER HAMPTONBAY HARDWICK HEIL HISENSE HOTPOINT ICP IMPERIAL INGLIS JANITROL JENNAIR JORDAN KELVINATOR KENMORE KITCHENAID LG LENNOX LITTON MAGICCHEF MAYCOR MAYTAG MENUMASTER MODERNMAID NEPTUNE NORCOLD NORDYNE NORGE NORTEK PARTNERSPLUS PAYNE PEERLESS PINNACLE PREMIERE PUREFIRE RCA RHEEM ROPER RUUD SAMSUNG SPEEDQUEEN STATE SUNRAY TAPPAN THERMADOR TRANE VIKING VIZIO WESTINGHOUSE WHIRLPOOL WHITEWESTINGHOUSE YORK

Decoding Responses

All responses are in JSON format. A standard http response code is always returned. In the case of multiple possible manufacture dates, we provide a confidence score for each of the possible dates.

An example of a decode returning multiple possible dates. The confidence score is calculated based on our internal data for similiar models as well as externally sourced data. Some properties like 'details' will only be filled if there is appropriate data.

{
  "result": {
    "status": 200,
    "message": "ok",
    "decoded": {
      "make": "WHIRLPOOL",
      "model": "WDT730PAHZ0",
      "serial": "F91720000",
      "mostLikelyYear": 2019,
      "details": {
        "averageListedPrice": 829,
        "type": "Dishwasher",
        "color": "Stainless Steel",
        "description": "24 Inch Fully Integrated Built-In Dishwasher with 15 Place Setting Capacity"
      },
      "yearOptions": {
        "2019": {
          "year": 2019,
          "confidence": 80,
          "fullDate": "2029-04-22T00:00:00.000000Z"
        }
      },
      "responseTime": 0.9700009822845459
    }
  }
}

In some cases it is not possible to narrow down the date any further due to a lack of existing data for the parameters supplied. This often happens due to a mistyped model or serial number but also could be due to an obscure model number. The following is an example of a serial number decoded but lacking supporting model data to narrow down the options.

{
  "result": {
    "status": 200,
    "message": "ok",
    "decoded": {
      "make": "GE",
      "model": "PSSUUUII",
      "serial": "MM499999",
      "mostLikelyYear": null,
      "details": [],
      "yearOptions": {
        "1995": {
          "year": 1995,
          "confidence": 33,
          "fullDate": "2005-07-01T01:00:00.000000Z"
        },
        "2007": {
          "year": 2007,
          "confidence": 33,
          "fullDate": "2007-07-01T01:00:00.000000Z"
        },
        "2019": {
          "year": 2019,
          "confidence": 33,
          "fullDate": "2019-07-01T01:00:00.000000Z"
        }
      },
      "responseTime": 1.2382619380950928
    }
  }
}

An example of a response returning a 400 error to the client due to the request missing parameters or supplying a non-supported make.

{
  "result": {
    "status": 400,
    "message": "Missing parameter or make value not in expected list.",
    "decoded": null
  }
}

An example of a response returning a 429 error to the client due to the free daily calls being exhausted.

{
  "result": {
    "status": 429,
    'message' => 'Free api calls exhausted. Setup a billing method for increased usage.',
    "decoded": null
  }
}

Copyright homespy.io 2023