Things

The primary entities indexed by Thingful are individual Things that exist somewhere out in the world, and that typically publish one or more sensor feeds containing data recorded from that specific physical location.

Typically you will use the Thingful API to search for Things out there matching some search criteria you have, however you can also use the Thingful API to request data for a Thing you already know the identifier of.

Search Things

GET /things

Search for things indexed by Thingful. If you make a request without specifying any query parameters you will receive a 400 Bad Request response, as the Thingful API currently requires you to specify some criteria when searching the API.

Example Request:

GET /things?q=pollution HTTP/1.1
Host: api.thingful.net
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Example Response:

HTTP/1.1 200 OK
Access-Control-Allow-Origin: *
Content-Type: application/vnd.api+json

{
  "links": {
    "next": "http://api.thingful.net/things?q=pollution&starting-after=002jw27y",
    "prev": "http://api.thingful.net/things?q=pollution&starting-before=001x1r8d",
    "self": "http://api.thingful.net/things?q=pollution"
  },
  "data": [
    {
      "type": "thing",
      "id": "001x1r8d",
      "attributes": {
        "title": "AtelierTen",
        "description": null,
        "webpage": "http://smartcitizen.me/devices/view/2474",
        "datasource": "http://api.smartcitizen.me/v0.0.1/{{apikey}}/2474/posts.json",
        "created_at": "2016-01-27T16:33:19.085Z",
        "updated_at": "2016-04-26T10:08:14.551Z",
        "indexed_at": "2016-04-26T10:08:14.551Z",
        "longitude": -0.076598525047302,
        "latitude": 51.5280098682548,
        "visibility": "open",
        "distance": null,
        "score": 0.521585421264172,
        "channels": [
          {
            "id": "bat",
            "value": "70",
            "recorded_at": "2015-12-14T12:14:22Z",
            "units": null
          },
          {
            "id": "co",
            "value": "100.677",
            "recorded_at": "2015-12-14T12:14:22Z",
            "units": null
          },
          {
            "id": "hum",
            "value": "52.9671020507812",
            "recorded_at": "2015-12-14T12:14:22Z",
            "units": null
          }
        ]
      },
      "relationships": {
        "category": {
          "data": {
            "type": "category",
            "id": "environment"
          }
        },
        "provider": {
          "links": {
            "related": "https://api.thingful.net/providers/smartcitizen"
          },
          "data": {
            "type": "provider",
            "id": "smartcitizen"
          }
        }
      }
    },
    {
      "type": "thing",
      "id": "002jw27y",
      "attributes": {
        "title": "Air quality station : ROCK_IS",
        "description": "Air quality station : ROCK_IS - Davenport-Moline-Rock Island, US",
        "webpage": "https://openaq.org",
        "datasource": "https://api.openaq.org/v1/latest?location=ROCK_IS",
        "created_at": "2016-03-07T11:15:02.593Z",
        "updated_at": "2016-03-29T09:35:28.573Z",
        "indexed_at": "2016-03-29T09:35:28.573Z",
        "longitude": -90.5172,
        "latitude": 41.5144,
        "visibility": "open",
        "distance": null,
        "score": 0.121585421264172,
        "channels": [
          {
            "id": "o3",
            "value": "0.002",
            "recorded_at": "2016-03-29T07:00:00Z",
            "units": "ppm"
          }
        ]
      },
      "relationships": {
        "category": {
          "data": {
            "type": "category",
            "id": "environment"
          }
        },
        "provider": {
          "links": {
            "related": "https://api.thingful.net/providers/openaq"
          },
          "data": {
            "type": "provider",
            "id": "openaq"
          }
        }
      }
    }
  ]
}
Query Parameters:
 
  • q – full text search string to only return things that match the given query.
  • geobound-minlong – numerical value representing the minimum longitude of a bounding box allowing clients to request things within a specific geographical area.
  • geobound-minlat – numerical value representing the minimum latitude of a bounding box allowing clients to request things within a specific geographical area.
  • geobound-maxlong – numerical value representing the maximum longitude of a bounding box allowing clients to request things within a specific geographical area.
  • geobound-maxlat – numerical value representing the maximum latitude of a bounding box allowing clients to request things within a specific geographical area.
  • geo-long – numerical value representing the longitude coordinate of geographic point allowing clients to request things within a specific geographical area.

:query geo-lat:numerical value representing the latitude coordinate of a geographic point allowing clients to request things within a specific geographical area. :query geo-radius: numerical value representing radius in meters allowing clients to request things within a specific geographical area. :query sort: parameter that specifies how results are sorted. Permitted values are score or distance. Default value is score meaning results are returned in order of _best_ to _worst_. Each value can also be negated by prefixing with a -, i.e. -distance. :query limit: numerical value indicating how many results should be returned in each response. Default value is 50. :query starting-after: string parameter used when paginating to navigate to the next page of results. The value of this parameter is calculated on the server, so clients should not expect to be able to infer the value for this parameter, rather they must just use the next link returned by the server. :query starting-before: string parameter used when paginating to navigate to the previous page of results. The value of this parameter is calculated on the server so clients should not expect to be able to infer the value of this parameter, rather they must just use the previous link returned by the server. :>jsonarr type: JSON API requires all resource documents to specify a type, all things return a type of thing. :>jsonarr id: The UID of the Thing :>jsonarr attributes: A JSON object containing the attributes of the Thing described below. :>json title: The title of the Thing :>json description: The description of the Thing (may be null). :status 200: response was handled successfully :status 400: client error - either a request with no parameters was made, or an invalid parameter combination was submitted. :status 500: internal server error

Get a Thing

GET /things/:id

Get a single thing with identifier id.

Example Request:

GET /things/1n6ty4sx HTTP/1.1
Host: api.thingful.net
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Example Response:

HTTP/1.1 200 OK
Access-Control-Allow-Origin: *
Content-Type: application/vnd.api+json

{
  "links": {
    "self": "https://api.thingful.net/things/002jw27y"
  },
  "data": {
    "type": "thing",
    "id": "002jw27y",
    "attributes": {
      "title": "Air quality station : ROCK_IS",
      "description": "Air quality station : ROCK_IS - Davenport-Moline-Rock Island, US",
      "webpage": "https://openaq.org",
      "datasource": "https://api.openaq.org/v1/latest?location=ROCK_IS",
      "created_at": "2016-03-07T11:15:02.593Z",
      "updated_at": "2016-03-29T09:35:28.573Z",
      "indexed_at": "2016-03-29T09:35:28.573Z",
      "longitude": -90.5172,
      "latitude": 41.5144,
      "visibility": "open",
      "distance": null,
      "score": null,
      "channels": [
        {
          "id": "o3",
          "value": "0.002",
          "recorded_at": "2016-03-29T07:00:00Z",
          "units": "ppm"
        }
      ]
    },
    "relationships": {
      "category": {
        "data": {
          "type": "category",
          "id": "environment"
        }
      },
      "provider": {
        "links": {
          "related": "https://api.thingful.net/providers/openaq"
        },
        "data": {
          "type": "provider",
          "id": "openaq"
        }
      }
    }
  }
}
Parameters:
  • id (string) – the unique Thingful id of the resource.
Query Parameters:
 
  • tag – if you pass an optional tag parameter you can restrict the channels returned to just those containing this tag.
Response Headers:
 
Status Codes: