{"openapi": "3.1.0", "info": {"title": "Tipspeed Beta", "version": "beta", "description": ""}, "paths": {"/api/beta/projects/": {"get": {"operationId": "list_projects", "summary": "List available projects", "parameters": [], "responses": {"200": {"description": "OK", "content": {"application/json": {"schema": {"items": {"$ref": "#/components/schemas/ProjectSchema"}, "title": "Response", "type": "array"}}}}}, "description": "Returns all wind farm projects accessible to the authenticated user. Always call this first to obtain the team_slug and project_slug required by other endpoints. simulation_data_range.end is the last date with data (inclusive); the endpoints taking a date range read their end as the closing stamp of a day, so pass the day after it to cover that date.", "security": [{"ApiKeyAuth": []}]}}, "/api/beta/projects/{team_slug}/{project_slug}/energy-chain-summary": {"get": {"operationId": "energy_chain_summary", "summary": "Get energy chain summary", "parameters": [{"in": "path", "name": "team_slug", "schema": {"description": "Team slug, obtained from the project list endpoint", "title": "Team Slug", "type": "string"}, "required": true, "description": "Team slug, obtained from the project list endpoint"}, {"in": "path", "name": "project_slug", "schema": {"description": "Project slug, obtained from the project list endpoint", "title": "Project Slug", "type": "string"}, "required": true, "description": "Project slug, obtained from the project list endpoint"}, {"in": "query", "name": "start", "schema": {"description": "Start date in ISO format (YYYY-MM-DD), UTC", "title": "Start", "type": "string"}, "required": true, "description": "Start date in ISO format (YYYY-MM-DD), UTC"}, {"in": "query", "name": "end", "schema": {"description": "Exclusive end date in ISO format (YYYY-MM-DD), UTC: the query stops before this day, so to include a last day such as simulation_data_range.end from the project list, pass the day after it", "title": "End", "type": "string"}, "required": true, "description": "Exclusive end date in ISO format (YYYY-MM-DD), UTC: the query stops before this day, so to include a last day such as simulation_data_range.end from the project list, pass the day after it"}], "responses": {"200": {"description": "OK", "content": {"application/json": {"schema": {"items": {"$ref": "#/components/schemas/EnergyChainStepSchema"}, "title": "Response", "type": "array"}}}}}, "description": "Returns the energy chain breakdown (gross to net) for the given date range.", "security": [{"ApiKeyAuth": []}]}}, "/api/beta/projects/{team_slug}/{project_slug}/query": {"get": {"operationId": "query", "summary": "Query project metrics over any combination of dimensions", "parameters": [{"in": "path", "name": "team_slug", "schema": {"description": "Team slug, obtained from the project list endpoint", "title": "Team Slug", "type": "string"}, "required": true, "description": "Team slug, obtained from the project list endpoint"}, {"in": "path", "name": "project_slug", "schema": {"description": "Project slug, obtained from the project list endpoint", "title": "Project Slug", "type": "string"}, "required": true, "description": "Project slug, obtained from the project list endpoint"}, {"in": "query", "name": "metrics", "schema": {"description": "Comma-separated metric keys; see /api/beta/catalogue/", "title": "Metrics", "type": "string"}, "required": true, "description": "Comma-separated metric keys; see /api/beta/catalogue/"}, {"in": "query", "name": "start", "schema": {"anyOf": [{"type": "string"}, {"type": "null"}], "description": "Start date ISO (YYYY-MM-DD), UTC; defaults to project start", "title": "Start"}, "required": false, "description": "Start date ISO (YYYY-MM-DD), UTC; defaults to project start"}, {"in": "query", "name": "end", "schema": {"anyOf": [{"type": "string"}, {"type": "null"}], "description": "Exclusive end date ISO (YYYY-MM-DD), UTC: the query stops before this day, so to include a last day such as simulation_data_range.end from the project list, pass the day after it. Omit it to cover everything up to the project's last available date", "title": "End"}, "required": false, "description": "Exclusive end date ISO (YYYY-MM-DD), UTC: the query stops before this day, so to include a last day such as simulation_data_range.end from the project list, pass the day after it. Omit it to cover everything up to the project's last available date"}, {"in": "query", "name": "period", "schema": {"default": "1d", "description": "Bucket rows by period: 10min, 1h, 1d (default), 1mo or 1y. Pass all for a single row totalling the whole date range, e.g. to answer 'how much over this period'. 10min allows at most 31 days and 1h at most 366 days between start and end", "enum": ["10min", "1h", "1d", "1mo", "1y", "all"], "title": "Period", "type": "string"}, "required": false, "description": "Bucket rows by period: 10min, 1h, 1d (default), 1mo or 1y. Pass all for a single row totalling the whole date range, e.g. to answer 'how much over this period'. 10min allows at most 31 days and 1h at most 366 days between start and end"}, {"in": "query", "name": "by_turbine", "schema": {"default": false, "description": "Return one row per turbine instead of a farm aggregate", "title": "By Turbine", "type": "boolean"}, "required": false, "description": "Return one row per turbine instead of a farm aggregate"}, {"in": "query", "name": "turbines", "schema": {"anyOf": [{"type": "string"}, {"type": "null"}], "description": "Comma-separated turbine ids to restrict the rows; cannot be combined with group", "title": "Turbines"}, "required": false, "description": "Comma-separated turbine ids to restrict the rows; cannot be combined with group"}, {"in": "query", "name": "group", "schema": {"anyOf": [{"type": "string"}, {"type": "null"}], "description": "Slug of a saved turbine group to restrict the rows to its turbines, as listed by list_turbine_groups; cannot be combined with turbines", "title": "Group"}, "required": false, "description": "Slug of a saved turbine group to restrict the rows to its turbines, as listed by list_turbine_groups; cannot be combined with turbines"}, {"in": "query", "name": "bin_by", "schema": {"anyOf": [{"type": "string"}, {"type": "null"}], "description": "Binnable metric key to group by; see catalogue bin_width", "title": "Bin By"}, "required": false, "description": "Binnable metric key to group by; see catalogue bin_width"}, {"in": "query", "name": "bin_width", "schema": {"anyOf": [{"type": "number"}, {"type": "null"}], "description": "Override the metric's declared bin width", "title": "Bin Width"}, "required": false, "description": "Override the metric's declared bin width"}, {"in": "query", "name": "bin_centered", "schema": {"anyOf": [{"type": "boolean"}, {"type": "null"}], "description": "Override whether bins are centred on their label", "title": "Bin Centered"}, "required": false, "description": "Override whether bins are centred on their label"}, {"in": "query", "name": "filter_by", "schema": {"anyOf": [{"type": "string"}, {"type": "null"}], "description": "Signal key whose value restricts which rows are aggregated", "title": "Filter By"}, "required": false, "description": "Signal key whose value restricts which rows are aggregated"}, {"in": "query", "name": "filter_min", "schema": {"anyOf": [{"type": "number"}, {"type": "null"}], "description": "Inclusive lower bound for filter_by", "title": "Filter Min"}, "required": false, "description": "Inclusive lower bound for filter_by"}, {"in": "query", "name": "filter_max", "schema": {"anyOf": [{"type": "number"}, {"type": "null"}], "description": "Exclusive upper bound for filter_by", "title": "Filter Max"}, "required": false, "description": "Exclusive upper bound for filter_by"}], "responses": {"200": {"description": "OK", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/MetricsResponseSchema"}}}}}, "description": "Aggregates registered metrics over a date range, optionally grouped by turbine, by time period, and by the bins of a binnable measure, and optionally restricted to rows whose value of some signal falls in a range. Call /api/beta/catalogue/ to discover metric keys, their units and which of them are binnable (a metric is binnable when its bin_width is not null). Every registered metric supports the turbine and period dimensions. Rows are daily unless period says otherwise: pass period=all for one total over the whole range. All times are UTC, and the response's start and end give the window actually covered.", "security": [{"ApiKeyAuth": []}]}}, "/api/beta/projects/{team_slug}/{project_slug}/turbines": {"get": {"operationId": "turbines", "summary": "List a project's turbines with their static properties", "parameters": [{"in": "path", "name": "team_slug", "schema": {"description": "Team slug, obtained from the project list endpoint", "title": "Team Slug", "type": "string"}, "required": true, "description": "Team slug, obtained from the project list endpoint"}, {"in": "path", "name": "project_slug", "schema": {"description": "Project slug, obtained from the project list endpoint", "title": "Project Slug", "type": "string"}, "required": true, "description": "Project slug, obtained from the project list endpoint"}, {"in": "query", "name": "metrics", "schema": {"anyOf": [{"type": "string"}, {"type": "null"}], "description": "Comma-separated metric keys to join onto each turbine", "title": "Metrics"}, "required": false, "description": "Comma-separated metric keys to join onto each turbine"}, {"in": "query", "name": "turbines", "schema": {"anyOf": [{"type": "string"}, {"type": "null"}], "description": "Comma-separated turbine ids to restrict the rows; cannot be combined with group", "title": "Turbines"}, "required": false, "description": "Comma-separated turbine ids to restrict the rows; cannot be combined with group"}, {"in": "query", "name": "group", "schema": {"anyOf": [{"type": "string"}, {"type": "null"}], "description": "Slug of a saved turbine group to restrict the rows to its turbines, as listed by list_turbine_groups; cannot be combined with turbines", "title": "Group"}, "required": false, "description": "Slug of a saved turbine group to restrict the rows to its turbines, as listed by list_turbine_groups; cannot be combined with turbines"}, {"in": "query", "name": "start", "schema": {"anyOf": [{"type": "string"}, {"type": "null"}], "description": "Start date ISO (YYYY-MM-DD), UTC; defaults to project start", "title": "Start"}, "required": false, "description": "Start date ISO (YYYY-MM-DD), UTC; defaults to project start"}, {"in": "query", "name": "end", "schema": {"anyOf": [{"type": "string"}, {"type": "null"}], "description": "Exclusive end date ISO (YYYY-MM-DD), UTC: the query stops before this day, so to include a last day such as simulation_data_range.end from the project list, pass the day after it. Omit it to cover everything up to the project's last available date", "title": "End"}, "required": false, "description": "Exclusive end date ISO (YYYY-MM-DD), UTC: the query stops before this day, so to include a last day such as simulation_data_range.end from the project list, pass the day after it. Omit it to cover everything up to the project's last available date"}], "responses": {"200": {"description": "OK", "content": {"application/json": {"schema": {"items": {"$ref": "#/components/schemas/TurbineSchema"}, "title": "Response", "type": "array"}}}}}, "description": "Returns one row per turbine: hub height, rotor diameter, model, position and elevation. Pass metrics to join aggregated metric values onto each turbine in the same call, which is equivalent to /query with by_turbine=true joined on the turbine id.", "security": [{"ApiKeyAuth": []}]}}, "/api/beta/projects/{team_slug}/{project_slug}/turbine-groups": {"get": {"operationId": "list_turbine_groups", "summary": "List a project's saved turbine groups", "parameters": [{"in": "path", "name": "team_slug", "schema": {"description": "Team slug, obtained from the project list endpoint", "title": "Team Slug", "type": "string"}, "required": true, "description": "Team slug, obtained from the project list endpoint"}, {"in": "path", "name": "project_slug", "schema": {"description": "Project slug, obtained from the project list endpoint", "title": "Project Slug", "type": "string"}, "required": true, "description": "Project slug, obtained from the project list endpoint"}], "responses": {"200": {"description": "OK", "content": {"application/json": {"schema": {"items": {"$ref": "#/components/schemas/TurbineGroupSchema"}, "title": "Response", "type": "array"}}}}}, "description": "Returns the turbine groups users saved on the project, each with its slug and turbine ids. Pass a slug as group to /query or /turbines to restrict the rows to that group's turbines. A group lists only the turbines present in the project's data.", "security": [{"ApiKeyAuth": []}]}}, "/api/beta/catalogue/": {"get": {"operationId": "catalogue", "summary": "Get Catalogue", "parameters": [], "responses": {"200": {"description": "OK", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/CatalogueSchema"}}}}}, "security": [{"ApiKeyAuth": []}]}}}, "components": {"schemas": {"DateRangeSchema": {"properties": {"start": {"description": "Start date (inclusive, UTC)", "format": "date", "title": "Start", "type": "string"}, "end": {"description": "Last date with data (inclusive, UTC). Query endpoints read their end as the closing stamp of a day, so pass the day after it to cover this date, or omit end", "format": "date", "title": "End", "type": "string"}}, "required": ["start", "end"], "title": "DateRangeSchema", "type": "object"}, "ProjectSchema": {"properties": {"slug": {"description": "Identifier of the project", "title": "Slug", "type": "string"}, "long_name": {"description": "Full name of the wind farm project", "title": "Long Name", "type": "string"}, "team_slug": {"description": "Slug of the team that owns the project", "title": "Team Slug", "type": "string"}, "latitude": {"anyOf": [{"type": "number"}, {"type": "null"}], "description": "Approximate latitude of the project (WGS84), rounded to 4 decimals (~11 m)", "title": "Latitude"}, "longitude": {"anyOf": [{"type": "number"}, {"type": "null"}], "description": "Approximate longitude of the project (WGS84), rounded to 4 decimals (~11 m)", "title": "Longitude"}, "simulation_data_range": {"anyOf": [{"$ref": "#/components/schemas/DateRangeSchema"}, {"type": "null"}], "description": "Date range for which simulation data is available"}}, "required": ["slug", "long_name", "team_slug"], "title": "ProjectSchema", "type": "object"}, "EnergyChainStepSchema": {"properties": {"name": {"description": "Name of this energy step \u2014 the analytics registry's label for the step's own level metric (e.g. 'Gross (representative period)', 'Production')", "title": "Name", "type": "string"}, "loss_name": {"anyOf": [{"type": "string"}, {"type": "null"}], "description": "Name of the loss applied at this step", "title": "Loss Name"}, "energy": {"description": "Total energy at this step in MWh", "title": "Energy", "type": "number"}, "delta": {"description": "Energy lost from the previous step in MWh", "title": "Delta", "type": "number"}, "description": {"anyOf": [{"type": "string"}, {"type": "null"}], "description": "Human-readable description of this step", "title": "Description"}, "comment": {"anyOf": [{"type": "string"}, {"type": "null"}], "description": "Additional comment", "title": "Comment"}, "expected_energy": {"anyOf": [{"type": "number"}, {"type": "null"}], "description": "Expected energy at this step in MWh", "title": "Expected Energy"}, "expected_delta": {"anyOf": [{"type": "number"}, {"type": "null"}], "description": "Expected loss from the previous step in MWh", "title": "Expected Delta"}, "delta_pct": {"anyOf": [{"type": "number"}, {"type": "null"}], "description": "Loss as percentage of incoming energy", "title": "Delta Pct"}, "efficiency_pct": {"anyOf": [{"type": "number"}, {"type": "null"}], "description": "Energy retained as percentage of incoming energy", "title": "Efficiency Pct"}, "expected_delta_pct": {"anyOf": [{"type": "number"}, {"type": "null"}], "description": "Expected loss as percentage of incoming energy", "title": "Expected Delta Pct"}, "delta_vs_expected": {"anyOf": [{"type": "number"}, {"type": "null"}], "description": "Measured delta minus expected delta (positive = worse)", "title": "Delta Vs Expected"}, "energy_vs_expected": {"anyOf": [{"type": "number"}, {"type": "null"}], "description": "Measured energy minus expected energy (positive = better)", "title": "Energy Vs Expected"}}, "required": ["name", "energy", "delta"], "title": "EnergyChainStepSchema", "type": "object"}, "MetricRowSchema": {"properties": {"time": {"anyOf": [{"type": "string"}, {"type": "null"}], "description": "UTC label of the row's period: YYYY-MM-DDTHH:MMZ for 10min and 1h, YYYY-MM-DD daily, YYYY-MM monthly, YYYY yearly; None for period=all. A 10min label is the timestamp of the underlying 10-minute record, and a 1h label the hour those timestamps fall in. Periods without any data are left out rather than returned with null values", "title": "Time"}, "turbine": {"anyOf": [{"type": "string"}, {"type": "null"}], "description": "Turbine identifier; None when no turbine dimension", "title": "Turbine"}, "bin": {"anyOf": [{"type": "number"}, {"type": "null"}], "description": "Bin centre of the binning dimension; None when no bin dimension", "title": "Bin"}, "values": {"additionalProperties": {"anyOf": [{"type": "number"}, {"type": "null"}]}, "description": "Metric values keyed by metric key", "title": "Values", "type": "object"}}, "required": ["values"], "title": "MetricRowSchema", "type": "object"}, "MetricsResponseSchema": {"properties": {"metrics": {"description": "Metric keys included in each row's values", "items": {"type": "string"}, "title": "Metrics", "type": "array"}, "dimensions": {"description": "Active dimensions: subset of ['turbine', 'period', 'bin']", "items": {"type": "string"}, "title": "Dimensions", "type": "array"}, "period": {"anyOf": [{"type": "string"}, {"type": "null"}], "description": "Aggregation period (10min, 1h, 1d, 1mo, 1y, or all for a single whole-range row)", "title": "Period"}, "start": {"anyOf": [{"format": "date-time", "type": "string"}, {"type": "null"}], "description": "Start of the window the rows cover (inclusive, UTC); None when the project has no data", "title": "Start"}, "end": {"anyOf": [{"format": "date-time", "type": "string"}, {"type": "null"}], "description": "End of the window the rows cover (exclusive, UTC); None when the project has no data", "title": "End"}, "rows": {"description": "One row per combination of the active dimensions (turbine, period and/or bin)", "items": {"$ref": "#/components/schemas/MetricRowSchema"}, "title": "Rows", "type": "array"}}, "required": ["metrics", "dimensions", "rows"], "title": "MetricsResponseSchema", "type": "object"}, "TurbineSchema": {"properties": {"point": {"description": "Turbine identifier", "title": "Point", "type": "string"}, "hub_height": {"anyOf": [{"type": "number"}, {"type": "null"}], "description": "Hub height in metres", "title": "Hub Height"}, "rotor_diameter": {"anyOf": [{"type": "number"}, {"type": "null"}], "description": "Rotor diameter in metres", "title": "Rotor Diameter"}, "turbine_model": {"anyOf": [{"type": "string"}, {"type": "null"}], "description": "Turbine model name", "title": "Turbine Model"}, "model_uri": {"anyOf": [{"type": "string"}, {"type": "null"}], "description": "Turbine model URI in the catalogue", "title": "Model Uri"}, "layout": {"anyOf": [{"type": "string"}, {"type": "null"}], "description": "Layout identifier", "title": "Layout"}, "label": {"anyOf": [{"type": "string"}, {"type": "null"}], "description": "Turbine label", "title": "Label"}, "longitude": {"anyOf": [{"type": "number"}, {"type": "null"}], "description": "Turbine longitude (WGS84), rounded to 6 decimals (~0.1 m)", "title": "Longitude"}, "latitude": {"anyOf": [{"type": "number"}, {"type": "null"}], "description": "Turbine latitude (WGS84), rounded to 6 decimals (~0.1 m)", "title": "Latitude"}, "elevation": {"anyOf": [{"type": "number"}, {"type": "null"}], "description": "Turbine elevation above sea level in metres", "title": "Elevation"}, "values": {"anyOf": [{"additionalProperties": {"anyOf": [{"type": "number"}, {"type": "null"}]}, "type": "object"}, {"type": "null"}], "description": "Requested metric values keyed by metric key; null when metrics was not given", "title": "Values"}}, "required": ["point"], "title": "TurbineSchema", "type": "object"}, "TurbineGroupSchema": {"properties": {"name": {"description": "Group name, as users see it", "title": "Name", "type": "string"}, "slug": {"description": "Group identifier, to pass as group to /query or /turbines", "title": "Slug", "type": "string"}, "turbines": {"description": "Turbine ids in the group that the project's data has", "items": {"type": "string"}, "title": "Turbines", "type": "array"}}, "required": ["name", "slug", "turbines"], "title": "TurbineGroupSchema", "type": "object"}, "CatalogueMetricSchema": {"properties": {"key": {"title": "Key", "type": "string"}, "label": {"title": "Label", "type": "string"}, "description": {"title": "Description", "type": "string"}, "kind": {"enum": ["measure", "derived"], "title": "Kind", "type": "string"}, "unit": {"anyOf": [{"type": "string"}, {"type": "null"}], "title": "Unit"}, "model": {"anyOf": [{"type": "string"}, {"type": "null"}], "title": "Model"}, "agg": {"anyOf": [{"type": "string"}, {"type": "null"}], "title": "Agg"}, "bin_width": {"anyOf": [{"type": "number"}, {"type": "null"}], "title": "Bin Width"}, "bin_centered": {"title": "Bin Centered", "type": "boolean"}, "depends_on": {"items": {"type": "string"}, "title": "Depends On", "type": "array"}, "formula_latex": {"anyOf": [{"type": "string"}, {"type": "null"}], "title": "Formula Latex"}}, "required": ["key", "label", "description", "kind", "unit", "model", "agg", "bin_width", "bin_centered", "depends_on", "formula_latex"], "title": "CatalogueMetricSchema", "type": "object"}, "CatalogueModelSchema": {"properties": {"key": {"title": "Key", "type": "string"}, "label": {"title": "Label", "type": "string"}, "description": {"title": "Description", "type": "string"}}, "required": ["key", "label", "description"], "title": "CatalogueModelSchema", "type": "object"}, "CatalogueSchema": {"properties": {"metrics": {"items": {"$ref": "#/components/schemas/CatalogueMetricSchema"}, "title": "Metrics", "type": "array"}, "models": {"items": {"$ref": "#/components/schemas/CatalogueModelSchema"}, "title": "Models", "type": "array"}, "signals": {"items": {"$ref": "#/components/schemas/CatalogueSignalSchema"}, "title": "Signals", "type": "array"}}, "required": ["metrics", "models", "signals"], "title": "CatalogueSchema", "type": "object"}, "CatalogueSignalSchema": {"properties": {"name": {"title": "Name", "type": "string"}, "label": {"anyOf": [{"type": "string"}, {"type": "null"}], "title": "Label"}, "kind": {"enum": ["feature", "source"], "title": "Kind", "type": "string"}, "unit": {"anyOf": [{"type": "string"}, {"type": "null"}], "title": "Unit"}, "column": {"anyOf": [{"type": "string"}, {"type": "null"}], "title": "Column"}, "model": {"anyOf": [{"type": "string"}, {"type": "null"}], "title": "Model"}}, "required": ["name", "label", "kind", "unit", "column", "model"], "title": "CatalogueSignalSchema", "type": "object"}}, "securitySchemes": {"ApiKeyAuth": {"type": "http", "scheme": "bearer"}}}, "servers": []}