================================= CarbonCulture API Documentation ================================= The CarbonCulture realtime energy data is avaialbe via the following API. The various meter readings come in the form of a timeseries of values which we call a channel. We provide channels for all available utilities for the place of participating organisations. Formats ======= API requests and responses can be made in the following formats. * JSON (recommended) * JSON-P * YAML * XML (if you must, but it's autogenerated so be warned) A successful request will result in a response with a status of "ok". Basic Requests ============== Simple requests can be made of the API using paths based URLs. Organisations Overview ---------------------- :URL: http://data.carbonculture.net/ organisations A list of organisations who are participating in CarbonCulture Organisation Info ----------------- :URL: http://data.carbonculture.net// :Example: http://data.carbonculture.net/decc/ Information about a given organisation:: place A list of place for this organisation organisation The organisation slug title Full organisation title Place Info ------------- :URL: http://data.carbonculture.net/// :Example: http://data.carbonculture.net/decc/whitehall-place/ Information about a building or place place The slug for the place link_url The URL for the building profile page at CarbonCulture channels A List of utility channels available for this building image_url An Image of the place. title The verbose name of the place building_stats A list of facts on the building such as - The year it was built - Type of Heating used - Number of floors - Total Usable Floor Area - Number of occupants - Electricity price - Price of gas Channel Info & Data ------------------- :URL: http://data.carbonculture.net// :Example: http://data.carbonculture.net/decc/whitehall-place/elec fields A List of the fields returned in the result. If with-timestamp is set to true, a field labelled 'timestamp' will be included normally as the first entry. start_time The start time range for the result results The data as a list of lists, the values are in the same order as the defined fields channel-info Various information about the channel such as:: - timestamp - first_timestamp - unit of measurement (e.g. kWh) - utility (e.g. Electricity) points The number of points in the result end_time The end of the time range for the result channel The full channel slug Cross Environment Requests -------------------------- The channel labels are namespaced and can be accessed at any level by completing the remainder of the channel label in the channel parameter. This way a number of channels may be specified at the same time to reduce round trip time to the CarbonCulture server. Example +++++++ - http://data.carbonculture.net/decc/whitehall-place/?channels=elec - http://data.carbonculture.net/decc/?channels=whitehall-place.elec - http://data.carbonculture.net/?channels=decc.whitehall-place.elec Parameters ---------- By default the results will be for the previous 24 hours. Any combination of start-time, end-time and hours can be given to alter this. By passing just end-time the results will be for the previous 24 hours before that time, and by passing start-time the results will be for 24 hours following that time. Passing both start-time and end-time will give results for the time between. The resolution of the individual points is currently limited to 30 minutes, if you require finer grained data (up to 5 seconds per point) please contact us. end-time defaults to now start-time defaults to 24 hours before end-time hours The number of hours to return results for, use with either start-time or end-time points The number of points to return between the two dates, limited to 1500 with-timestamp A boolean to include timestamps in the results callback If you would like JSON-P instead of JSON (to request the data from a browser on your own domain). JQuery should handle this for you though. allow-none Bool, ask CarbonCulture to return null values instead of 0 for missing data.