HTTP
To retrieve your data, you will only need your PUBLIC_KEY
. All data on data.sparkfun.com should be considered publicly accessible, but you can host your own phant server if you would like your data to be private.
Data Formats
Data is currently available in CSV
, JSON
, and JSONP
formats, but more formats will be available soon. If you would like to see a specific output format supported, submit an issue on GitHub, and we will try to make it available.
Paging
By default, data.sparkfun.com returns all of your logged data in the format you requested. If there is a need, you can also request output in 250 kilobyte chunks by setting the page
parameter in the query string portion of the URL. This can be very helpful if you just want to check out the latest logged data without requesting the entire data set.
HTTP Request Examples
Data can be retrieved by using your PUBLIC_KEY
to make a HTTP GET
request for the FORMAT
you would like returned by the server. Data will be returned in reverse chronological order.
curl -X GET 'http://data.sparkfun.com/output/PUBLIC_KEY.json'
Example Retrieve the first page of data in CSV format:
curl -X GET 'http://data.sparkfun.com/output/PUBLIC_KEY.csv?page=1'
The CSV response would look like this:
humidity,temp,timestamp
2,3,2014-06-25T21:35:29.827Z
86%,91.4,2014-06-25T21:10:08.112Z
86%,91.4,2014-06-25T20:40:56.425Z
Filters
Filters can be added to the output query string using the following format: FILTER[FIELD]=VALUE
.
FILTER
- the short name of the filter you would like to use. i.e.gte
FIELD
- the name of one of the fields you defined (or the auto generated timestamp field). i.e.temperature
VALUE
- the value used to compare against the values of the field you specified. The value is used in different ways by each filter, so check the documentation for the filter you are using in order to find acceptable values.
Grep for value (grep)
?grep[FIELD]=VALUE
The VALUE
can be any valid Javascript regex pattern.
https://data.sparkfun.com/output/xROQyrNEMoU6xQA2wro1?grep[humidity]=2952$
https://data.sparkfun.com/output/xROQyrNEMoU6xQA2wro1?grep[wood]=^bl
Equal to value (eq)
?eq[FIELD]=VALUE
The VALUE
can be any string or number. Numbers will be parsed as floats for comparison.
https://data.sparkfun.com/output/xROQyrNEMoU6xQA2wro1?eq[temp]=98.6
https://data.sparkfun.com/output/xROQyrNEMoU6xQA2wro1?eq[name]=black%20walnut
Not equal to value (ne)
?ne[FIELD]=VALUE
The VALUE
can be any string or number. Numbers will be parsed as floats for comparison.
https://data.sparkfun.com/output/xROQyrNEMoU6xQA2wro1?ne[temp]=98.6
Greater than value (gt)
?gt[FIELD]=VALUE
The VALUE
can be any number or in the case of the timestamp field, any date.js compatible string. Numbers will be parsed as floats for comparison.
Temp greater than 100: https://data.sparkfun.com/output/xROQyrNEMoU6xQA2wro1?gt[temp]=100.0
Get the last day of logged values: https://data.sparkfun.com/output/xROQyrNEMoU6xQA2wro1?gt[timestamp]=now%20-1day
Less than value (lt)
?lt[FIELD]=VALUE
The VALUE
can be any number or in the case of the timestamp field, any date.js compatible string. Numbers will be parsed as floats for comparison.
Temp less than 80: https://data.sparkfun.com/output/xROQyrNEMoU6xQA2wro1?lt[temp]=80.0
Get the logged values older than 11/30/2014: https://data.sparkfun.com/output/xROQyrNEMoU6xQA2wro1?lt[timestamp]=11-30-2014
Greater than value (gte)
?gte[FIELD]=VALUE
The VALUE
can be any number or in the case of the timestamp field, any date.js compatible string. Numbers will be parsed as floats for comparison.
Temp greater than or equal to 100: https://data.sparkfun.com/output/xROQyrNEMoU6xQA2wro1?gte[temp]=100.0
Get the logged values from 11/30/2014 or newer: https://data.sparkfun.com/output/xROQyrNEMoU6xQA2wro1?gte[timestamp]=12-02-2014
Less than or equal to value (lte)
?lte[FIELD]=VALUE
The VALUE
can be any number or in the case of the timestamp field, any date.js compatible string. Numbers will be parsed as floats for comparison.
Temp less than or equal to 80: https://data.sparkfun.com/output/xROQyrNEMoU6xQA2wro1?lte[temp]=80.0
Get the logged values from 11/30/2014 or older: https://data.sparkfun.com/output/xROQyrNEMoU6xQA2wro1?lte[timestamp]=11-30-2014
Combining Filters
You can combine as many filters as you would like using standard query string syntax.
Get the logged values from 11/30/2014 or older with a temp greater than or equal to 100: https://data.sparkfun.com/output/xROQyrNEMoU6xQA2wro1?lte[timestamp]=11-30-2014>e[temp]=100.0
Output Formats
JSONP Output
If you are using JavaScript in a web browser to retrieve data, then you might be interested in using the JSONP format. JSONP allows you to make to requests from a server from a different domain, which is normally not possible because of the same-origin policy.
Unlike all of the other methods, JSONP responses will always be sent with the HTTP 200
success code. We respond this way for the JSONP format because browsers will not parse the response body when the server replies with a HTTP error code.
Example Retrieve the first page of data in JSONP format with jQuery:
var public_key = 'YOUR_PUBLIC_KEY';
$.ajax({
url: 'http://data.sparkfun.com/output/' + public_key + '.json',
jsonp: 'callback',
cache: true,
dataType: 'jsonp',
data: {
page: 1
},
success: function(response) {
// response will be a javascript
// array of objects
console.log(response);
}
});
The JSONP response to this request would look like this:
typeof handler === 'function' && handler([{"humidity":"2","temp":"3","timestamp":"2014-06-25T21:35:29.827Z"},{"humidity":"86%","temp":"91.4","timestamp":"2014-06-25T21:10:08.112Z"},{"humidity":"86%","temp":"91.4","timestamp":"2014-06-25T20:40:56.425Z"}]);