{"openapi":"3.1.0","info":{"title":"Opin gögn governed data API","version":"2026-09-17","description":"Agreed measures over Icelandic public datasets, asked through a semantic model. Send measure and dimension NAMES; SQL is generated and returned for checking, and is never accepted as input."},"servers":[{"url":"https://opingogn.metadata.is"}],"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer"}},"schemas":{"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["DATASET_NOT_FOUND","MEASURE_NOT_FOUND","DIMENSION_NOT_FOUND","INVALID_FILTER","INVALID_REQUEST","DIMENSION_VALUE_NOT_FOUND","QUERY_TOO_COMPLEX","RESULT_LIMIT_EXCEEDED","QUERY_TIMEOUT","AUTH_REQUIRED","RATE_LIMITED","SERVER_BUSY","WAREHOUSE_UNAVAILABLE","INTERNAL_ERROR"]},"message":{"type":"string"},"details":{"type":"object"}}}}},"QueryRequest":{"type":"object","required":["dataset","measures"],"additionalProperties":false,"properties":{"dataset":{"type":"string"},"measures":{"type":"array","items":{"type":"string"},"minItems":1},"group_by":{"type":"array","items":{"type":"string"},"description":"dimension names, and/or year / month"},"filters":{"type":"object","additionalProperties":{"type":["string","number"]},"description":"dimension name -> exact value from the values endpoint"},"years":{"type":"array","items":{"type":"integer"}},"months":{"type":"array","items":{"type":"string","pattern":"^\\d{4}-\\d{2}$"}},"top":{"type":"integer","minimum":1}}}},"responses":{"Error":{"description":"A failure with a stable code","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"security":[{"bearer":[]},{}],"paths":{"/v1/datasets":{"get":{"operationId":"listDatasets","summary":"List datasets with their measures, dimensions and freshness","responses":{"200":{"description":"Datasets"},"429":{"$ref":"#/components/responses/Error"}}}},"/v1/datasets/{dataset}":{"get":{"operationId":"describeDataset","summary":"Measures, dimensions, caveats, glossary, limits, freshness","parameters":[{"name":"dataset","in":"path","required":true,"schema":{"type":"string"}},{"name":"lang","in":"query","schema":{"type":"string","enum":["en","is"]}}],"responses":{"200":{"description":"Dataset card"},"404":{"$ref":"#/components/responses/Error"}}}},"/v1/datasets/{dataset}/dimensions/{dimension}/values":{"get":{"operationId":"dimensionValues","summary":"Exact spellings of a dimension, bounded and paged","parameters":[{"name":"dataset","in":"path","required":true,"schema":{"type":"string"}},{"name":"dimension","in":"path","required":true,"schema":{"type":"string"}},{"name":"search","in":"query","schema":{"type":"string"}},{"name":"prefix","in":"query","schema":{"type":"boolean"}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1}},{"name":"cursor","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"Values"},"400":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"}}}},"/v1/datasets/{dataset}/verified":{"get":{"operationId":"verifiedQuestions","summary":"Worked examples: question, semantic request, SQL","parameters":[{"name":"dataset","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Examples"},"404":{"$ref":"#/components/responses/Error"}}}},"/v1/health/freshness":{"get":{"operationId":"freshnessHealth","summary":"Freshness of every dataset: fresh, warning, stale or unknown, and refresh outcomes","responses":{"200":{"description":"Aggregate and per-dataset freshness"}}}},"/v1/query":{"post":{"operationId":"query","summary":"Get numbers from agreed measures","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/QueryRequest"}}}},"responses":{"200":{"description":"Rows plus provenance"},"400":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"},"504":{"$ref":"#/components/responses/Error"}}}}}}