Introduction

This document describes how to use the REST API from The Measure of Things. The purpose of this API is to let you use our measurement data in your own web projects.

To begin using the API, you must sign up for an account. For details, see the Authentication section.

Authentication

Accessing measurement information requires an authenticated account. When you call the API, your request will be authenticated using the combination of your API key and the server from which your request originates.

To sign up for an account and obtain an API key, click here.

Bluebulb Projects reserves the right to change the terms of access to our API in the future.

Basics

The Measure of Things REST API is based on open standards, and can be integrated using multiple programming languages. It is accessible using a pattern of URI paths which provide access to specific resources. The API uses HTTP methods (primarily GET) and provides JSON object responses.

The API supports both the HTTP protocol and the HTTPS protocol.

The general form of the REST API is as follows:

[protocol]://mot-api.themeasureofthings.com/[version]/[resource]/[verb]?[arguments]

The current live version of the API is v1. This version number is used in the URI.

/measures

Returns a list of available measurement types. The measure value of each type is a required parameter for other requests, including requests against the items resource. The call also returns an adjective and noun for the measurement type.

Methods: GET

Request Parameters:

Parameter	Required?	Type	Description
key	Optional*	string	Your private API key associated with your account and the server making the request

*The key parameter must be included, but it may be passed either as a parameter in the query string or given in the X-API-Key parameter of the request header

Request Model:
Example:

GET //mot-api.themeasureofthings.com/v1/measures/?key=00000000-1111-2222-3333-444444444444

Response Model:
Example:

{
   "measures":[
      {
         "measure":"weight",
         "comparison_adjective":"heavy",
         "comparison_noun":"weight"
      },
      ...
   ]
}

Understanding and Interpreting the Response:
The purpose of the measures resource is to get the list of available enum values that can be passed when calling the item resource. These parameters do not change often and the response to this call may be cached locally. The response also includes information about the measure that can be used to construct a meaningful phrase.

In the above example, the measure value of weight is returned and can be used for subsequent calls, while the comparison_adjective and comparison_noun values of the reponse can be used to phrase the description of the results of subsequent calls, i.e. "as heavy as" or "the weight of."

Response Codes:
200: Returned if the request was correctly formatted, the resource exists, and the requestor has access to it.

403: Returned if the key parameter was not specified

{ 
   "error":"Parameter key was not supplied"
}

403: Returned if the key parameter and/or requesting server did not match a valid account

{ 
   "error":"Origin and/or parameter key are not valid"
}

405: Returned if a method other than GET was used in the request

{ 
   "error":"Measures endpoint only accepts GET requests"
}

500: Returned if there was an internal server error

{
   "error":"Unrecoverable error. Code 0000. Please contact the webmaster."
}

{ 
   "error":"Internal Server Error. Code 0010"
}

{ 
   "error":"Internal Server Error. Code 0012"
}

{ 
   "error":"Internal Server Error. Code 0013"
}

{ 
   "error":"Internal Server Error. Code 0014"
}

{ 
   "error":"Internal Server Error. Code 0016"
}

/units

Returns a list of available units for a given measure. The unit value of each type is a required parameter for other requests, including requests against the items resource. The call also returns a descriptive name of the unit.

Methods: GET

Request Parameters:

Parameter	Required?	Type	Description
key	Optional*	string	Your private API key associated with your account and the server making the request
measure	Required	string	An enum value corresponding to the measure for which you want a units list. Allowable values are those returned from the /measures resource

*The key parameter must be included, but it may be passed either as a parameter in the query string or given in the X-API-Key parameter of the request header

Request Model:
Example:

GET //mot-api.themeasureofthings.com/v1/units/weight/?key=00000000-1111-2222-3333-444444444444

Response Model:
Example:

{
   "measure":"weight",
   "units":[
      {
         "unit":"lbs",
         "unit_description":"pounds"
      },
      ...
   ]
}

Understanding and Interpreting the Response:
The purpose of the units resource is to get the list of available enum values that can be passed when calling the item resource. These parameters do not change often and the response to this call may be cached locally. The response also includes the descriptive name of the unit that can be used to construct a result phrase.

In the above example, the measure value of weight is returned. This validates that the response matches the request parameter. Each unit corresponding to the measure is returned separately withint the response array. Within each, the unit value is returned and can be used for subsequent calls. The longer description of the unit is also provided in the unit_description value, "pounds" in the above example.

Response Codes:
200: Returned if the request was correctly formatted, the resource exists, and the requestor has access to it.

400: Returned if the required measure parameter was not specified

{ 
   "error":"No measure parameter was supplied"
}

403: Returned if the key parameter was not specified

{ 
   "error":"Parameter key was not supplied"
}

403: Returned if the key parameter and/or requesting server did not match a valid account

{ 
   "error":"Origin and/or parameter key are not valid"
}

404: Returned if there are no valid units defined for the given measure parameter

{ 
   "error":"Measure does not have any units"
}

405: Returned if a method other than GET was used in the request

{ 
   "error":"Units endpoint only accepts GET requests"
}

500: Returned if there was an internal server error

{
   "error":"Unrecoverable error. Code 0000. Please contact the webmaster."
}

{ 
   "error":"Internal Server Error. Code 0011"
}

{ 
   "error":"Internal Server Error. Code 0012"
}

{ 
   "error":"Internal Server Error. Code 0013"
}

{ 
   "error":"Internal Server Error. Code 0015"
}

{ 
   "error":"Internal Server Error. Code 0019"
}

/items

Returns an item based on the the supplied measurement parameters, and descriptive information about the item.

Methods: GET

Request Parameters:

Parameter	Required?	Type	Description
key	Optional*	string	Your private API key associated with your account and the server making the request
verb	Required	string	Either search or random. search will return the closest measurement match to an item, based on the supplied parameters random will return a random item without regard to how it compares to the supplied parameters
measure	Required	string	An enum value corresponding to the measure for your input. Allowable values are those returned from the /measures resource
unit	Required	string	An enum value corresponding to the unit for your input. Allowable values are those returned from the /units resource
amount	Required	float	An numeric, non-negative value.

*The key parameter must be included, but it may be passed either as a parameter in the query string or given in the X-API-Key parameter of the request header

Request Model:
Example:

GET //mot-api.themeasureofthings.com/v1/items/search?measure=weight&unit=lbs&amount=100&key=00000000-1111-2222-3333-444444444444

Response Model:
Example:

{
   "measure":"weight",
   "unit":"lbs",
   "amount":"100",
   "unit_description":"pounds",
   "comparison_adjective":"heavy",
   "comparison_noun":"weight",
   "item":[
      {
         "item_article":"an",
         "item_description":"Octopus",
         "coefficient":0.91,
         "inverse_coefficient":1.1,
         "measurement":110,
         "significant_digits":2
      }
      ...
   ]
}

Understanding and Interpreting the Response:
This resource returns the actual items that are nearest to your input parameters. For both verbs, search and random, the result is structured in the same way. The difference is merely whether or not the data returned represents real items.

In the above example, the measure, unit, and amount values of weight, lbs, and 100, respectively, are returned. This validates that the response matches the request. The response also includes the full description of the unit, given in the unit_description value, here pounds. Additionally the comparison_adjective and comparison_noun values can be used to phrase a description of the results, i.e. "as heavy as" or "the weight of."

Within the item array, details about the result item are given. In the above example, the item_article and item_description values can be used to construct a description of the item, "an Octopus." The article and description are provided separately in case you do not wish to use the article.

Several numerical values are also provided in the response. The coefficient value is the value by which the measurement of the returned item must be multiplied to get the amount parameter in terms of the unit parameter. For the above example, 100 lbs is 0.91 times the weight of an Octopus. The inverse_coefficient value, meanwhile, is the value by which the amount must be multiplied in to get the returned item's measurement; an Octopus weighs 1.1 times 100 lbs. Finally, the measurement value is the actual measurement, in terms of the unit of the returned item; an octopus weighs 110 lbs.

Response Codes:
200: Returned if the request was correctly formatted, the resource exists, and the requestor has access to it.

400: Returned if the verb parameter was not specified

{ 
   "error":"Parameter verb was not supplied"
}

403: Returned if the key parameter was not specified

{ 
   "error":"Parameter key was not supplied"
}

403: Returned if the key parameter and/or requesting server did not match a valid account

{ 
   "error":"Origin and/or parameter key are not valid"
}

404: Returned if a verb parameter with a value other than search or random is supplied

{ 
   "error":"Verb invalid: [verb parameter]"
}

404: Returned if a measure parameter was not supplied

{ 
   "error":"Parameter measure was not supplied"
}

404: Returned if a unit parameter was not supplied

{ 
   "error":"Parameter unit was not supplied"
}

404: Returned if an amount parameter was not supplied

{ 
   "error":"Parameter amount was not supplied"
}

404: Returned if the amount parameter was a negative number

{ 
   "error":"Parameter amount must be positive"
}

404: Returned if the amount parameter was not numeric

{ 
   "error":"Parameter amount must be numeric"
}

404: Returned if the unit parameter supplied was not an allowable value in combination with the measure parameter. The /units resource provides a list of allowable parameters for a given measure

{ 
   "error":"Parameters measure and unit were supplied in an invalid combination: [measure], [unit]"
}

405: Returned if a method other than GET was used in the request

{ 
   "error":"Items endpoint only accepts GET requests"
}

500: Returned if there was an internal server error

{
   "error":"Unrecoverable error. Code 0000. Please contact the webmaster."
}

{
   "error":"Internal Server Error. Code 0012."
}

{
   "error":"Internal Server Error. Code 0013."
}

{
   "error":"Internal Server Error. Code 0018."
}

/testitems

Returns fake item information based on the the supplied measurement parameters, and descriptive information about the item. The /testitems resource is provided for testing purposes. It behaves identically to the /items resource, except for the data it returns.

Methods: GET

Request Parameters:

Parameter	Required?	Type	Description
key	Optional*	string	Your private API key associated with your account and the server making the request
verb	Required	string	Either search or random. search will return the closest measurement match to an item, based on the supplied parameters random will return a random item without regard to how it compares to the supplied parameters
measure	Required	string	An enum value corresponding to the measure for your input. Allowable values are those returned from the /measures resource
unit	Required	string	An enum value corresponding to the unit for your input. Allowable values are those returned from the /units resource
amount	Required	float	An numeric, non-negative value.

*The key parameter must be included, but it may be passed either as a parameter in the query string or given in the X-API-Key parameter of the request header

Request Model:
Example:

GET //mot-api.themeasureofthings.com/v1/testitems/search?measure=weight&unit=lbs&amount=100&key=00000000-1111-2222-3333-444444444444

Response Model:
Example:

{
   "measure":"weight",
   "unit":"lbs",
   "amount":"100",
   "unit_description":"pounds",
   "comparison_adjective":"heavy",
   "comparison_noun":"weight",
   "item":[
      {
         "item_article":"a",
         "item_description":"Test weight item E",
         "coefficient":0.8,
         "inverse_coefficient":1.25,
         "measurement":125,
         "significant_digits":3
      }
      ...
   ]
}

Understanding and Interpreting the Response:
This resource returns fake items details that are nearest to your input parameters. In all other aspects, it works the same way as the /measures For both verbs, search and random, the result is structured in the same way. The difference is merely whether or not the data returned represents real items.

In the above example, the measure, unit, and amount values of weight, lbs, and 100, respectively, are returned. This validates that the response matches the request. The response also includes the full description of the unit, given in the unit_description value, here pounds. Additionally the comparison_adjective and comparison_noun values can be used to phrase a description of the results, i.e. "as heavy as" or "the weight of."

Within the item array, details about the result item are given. In the above example, the item_article and item_description values can be used to construct a description of the item, "an Octopus." The article and description are provided separately in case you do not wish to use the article.

Several numerical values are also provided in the response. The coefficient value is the value by which the measurement of the returned item must be multiplied to get the amount parameter in terms of the unit parameter. For the above example, 100 lbs is 0.91 times the weight of an Octopus. The inverse_coefficient value, meanwhile, is the value by which the amount must be multiplied in to get the returned item's measurement; an Octopus weighs 1.1 times 100 lbs. Finally, the measurement value is the actual measurement, in terms of the unit of the returned item; an octopus weighs 110 lbs.

Response Codes:
200: Returned if the request was correctly formatted, the resource exists, and the requestor has access to it.

400: Returned if the verb parameter was not specified

{ 
   "error":"Parameter verb was not supplied"
}

403: Returned if the key parameter was not specified

{ 
   "error":"Parameter key was not supplied"
}

403: Returned if the key parameter and/or requesting server did not match a valid account

{ 
   "error":"Origin and/or parameter key are not valid"
}

404: Returned if a verb parameter with a value other than search or random is supplied

{ 
   "error":"Verb invalid: [verb parameter]"
}

404: Returned if a measure parameter was not supplied

{ 
   "error":"Parameter measure was not supplied"
}

404: Returned if a unit parameter was not supplied

{ 
   "error":"Parameter unit was not supplied"
}

404: Returned if an amount parameter was not supplied

{ 
   "error":"Parameter amount was not supplied"
}

404: Returned if the amount parameter was a negative number

{ 
   "error":"Parameter amount must be positive"
}

404: Returned if the amount parameter was not numeric

{ 
   "error":"Parameter amount must be numeric"
}

404: Returned if the unit parameter supplied was not an allowable value in combination with the measure parameter. The /units resource provides a list of allowable parameters for a given measure

{ 
   "error":"Parameters measure and unit were supplied in an invalid combination: [measure], [unit]"
}

405: Returned if a method other than GET was used in the request

{ 
   "error":"Testitems endpoint only accepts GET requests"
}

500: Returned if there was an internal server error

{
   "error":"Unrecoverable error. Code 0000. Please contact the webmaster."
}

{
   "error":"Internal Server Error. Code 0012."
}

{
   "error":"Internal Server Error. Code 0013."
}

{
   "error":"Internal Server Error. Code 0018."
}