json NxtPort Bel Air API

Posted 2021-05-18

{
  "swagger": "2.0",
  "info": {
    "title": "Bel Air API (staging)",
    "version": "v1",
    "description": "API for querying air quality data. Different layers of and time slices for each metric can be queried. The project is part of the Antwerp Smart Zone initiative.",
    "termsOfService": "https://www.nxtport.eu/General-Terms-And-Conditions",
    "contact": {
      "email": "[e-mail]"
    }
  },
  "schemes": [
    "https"
  ],
  "host": "api-stg.nxtport.eu",
  "basePath": "/belair/v1",
  "security": [
    {
      "SubscriptionKey": []
    }
  ],
  "securityDefinitions": {
    "SubscriptionKey": {
      "type": "apiKey",
      "in": "header",
      "name": "Ocp-Apim-Subscription-Key"
    }
  },
  "paths": {
    "/metrics": {
      "get": {
        "operationId": "getMetrics",
        "produces": [
          "application/json"
        ],
        "responses": {
          "200": {
            "description": "OK",
            "schema": {
              "items": {
                "$ref": "#/definitions/Metric"
              },
              "type": "array"
            },
            "examples": {
              "application/json": [
                [
                  {
                    "granularity": "HOURLY",
                    "id": "airquality.no2"
                  },
                  {
                    "granularity": "HOURLY",
                    "id": "airquality.pm1"
                  },
                  {
                    "granularity": "HOURLY",
                    "id": "airquality.pm10"
                  },
                  {
                    "granularity": "HOURLY",
                    "id": "airquality.pm25"
                  },
                  {
                    "granularity": "HOURLY",
                    "id": "environment.light"
                  },
                  {
                    "granularity": "HOURLY",
                    "id": "environment.relativehumidity"
                  },
                  {
                    "granularity": "HOURLY",
                    "id": "environment.temperature"
                  }
                ]
              ]
            }
          }
        },
        "summary": "Retrieving supported metrics",
        "description": "The platform allows you to retrieve supported metrics by sending a HTTP GET to /metrics. \nThe string-values for the attribute id can be used as a metricId path parameter in the City Layer operations. \nThe attribute granularity indicates how fine grained temporal pages should be split up when querying individual sources (and can be ignored here)."
      }
    },
    "/layers": {
      "get": {
        "operationId": "getLayers",
        "produces": [
          "application/json"
        ],
        "responses": {
          "200": {
            "description": "OK",
            "schema": {
              "items": {
                "type": "string"
              },
              "type": "array"
            },
            "examples": {
              "application/json": [
                [
                  "antwerp_medium_detail",
                  "roadshow_high_detail",
                  "antwerp_high_detail"
                ]
              ]
            }
          }
        },
        "summary": "Retrieve available layers",
        "description": "This operation lists the currently available city layers. \nThe returned strings can then be used as a layerId path parameter in the /layers operations included in this API."
      }
    },
    "/layers/{layerId}/{metricId}/{date}": {
      "get": {
        "operationId": "getLayerDateByLayerMetricDate",
        "parameters": [
          {
            "in": "path",
            "name": "layerId",
            "required": true,
            "type": "string",
            "description": "TODO"
          },
          {
            "in": "path",
            "name": "metricId",
            "required": true,
            "type": "string",
            "description": "TODO"
          },
          {
            "in": "path",
            "name": "date",
            "required": true,
            "type": "number",
            "description": "TODO"
          }
        ],
        "produces": [
          "application/json"
        ],
        "responses": {
          "200": {
            "description": "OK",
            "schema": {
              "$ref": "#/definitions/CityLayerData"
            },
            "examples": {
              "application/json": {
                "name": "airquality.no2/20180314",
                "columns": [
                  "geohash",
                  "mean",
                  "min",
                  "max",
                  "stddev",
                  "count"
                ],
                "values": [
                  [
                    "u155kmy",
                    71,
                    71,
                    71,
                    0,
                    1
                  ],
                  [
                    "u155kmw",
                    85.50959930419921,
                    71,
                    96.74565124511719,
                    0.4018735901885278,
                    5
                  ],
                  [
                    "u155kmq",
                    71,
                    71,
                    71,
                    0,
                    2
                  ],
                  [
                    "u155kmu",
                    71,
                    71,
                    71,
                    0,
                    12
                  ],
                  [
                    "u155m44",
                    13,
                    13,
                    13,
                    0,
                    1
                  ],
                  [
                    "u155kpv",
                    81,
                    81,
                    81,
                    0,
                    2
                  ]
                ]
              }
            }
          }
        },
        "summary": "Retrieve the city layer data for the specified layer, metric and date.",
        "description": "This operation retrieves city layer data for the specified layer, metric and date combination. The date is passed in the following format: YYYYMMDD. The values for the layerId and metricId can be fetched from the /layers and /metrics operations."
      }
    },
    "/layers/{layerId}/{metricId}/{date}/{hour}": {
      "get": {
        "operationId": "getLayerDateByLayerMetricDateHour",
        "parameters": [
          {
            "in": "path",
            "name": "layerId",
            "required": true,
            "type": "string",
            "description": "TODO"
          },
          {
            "in": "path",
            "name": "metricId",
            "required": true,
            "type": "string",
            "description": "TODO"
          },
          {
            "in": "path",
            "name": "date",
            "required": true,
            "type": "number",
            "description": "TODO"
          },
          {
            "in": "path",
            "name": "hour",
            "required": true,
            "type": "number",
            "description": "TODO"
          }
        ],
        "produces": [
          "application/json"
        ],
        "responses": {
          "200": {
            "description": "OK",
            "schema": {
              "$ref": "#/definitions/CityLayerData"
            },
            "examples": {
              "application/json": {
                "name": "airquality.no2/20180314",
                "columns": [
                  "geohash",
                  "mean",
                  "min",
                  "max",
                  "stddev",
                  "count"
                ],
                "values": [
                  [
                    "u155kmy",
                    71,
                    71,
                    71,
                    0,
                    1
                  ],
                  [
                    "u155kmw",
                    85.50959930419921,
                    71,
                    96.74565124511719,
                    0.4018735901885278,
                    5
                  ],
                  [
                    "u155kmq",
                    71,
                    71,
                    71,
                    0,
                    2
                  ],
                  [
                    "u155kmu",
                    71,
                    71,
                    71,
                    0,
                    12
                  ],
                  [
                    "u155m44",
                    13,
                    13,
                    13,
                    0,
                    1
                  ],
                  [
                    "u155kpv",
                    81,
                    81,
                    81,
                    0,
                    2
                  ]
                ]
              }
            }
          }
        },
        "summary": "Retrieve the city layer data for the specified layer, metric and date.",
        "description": "This operation retrieves city layer data for the specified layer, metric and date combination. The date is passed in the following format: YYYYMMDD. The values for the layerId and metricId can be fetched from the /layers and /metrics operations."
      }
    }
  },
  "definitions": {
    "Metric": {
      "title": "Metric",
      "type": "object",
      "properties": {
        "granularity": {
          "type": "string",
          "description": "The attribute granularity indicates how fine grained temporal pages should be split up when querying individual sources (and can be ignored here)."
        },
        "id": {
          "type": "string",
          "description": "The string-values for the attribute id can be used as a metricId path parameter in the City Layer operations."
        }
      },
      "required": [
        "id",
        "granularity"
      ]
    },
    "CityLayerData": {
      "title": "CityLayerData",
      "type": "object",
      "properties": {
        "name": {
          "type": "string",
          "description": "The attribute name is a reference for this piece of data and can be ignored. "
        },
        "columns": {
          "items": {
            "type": "string"
          },
          "type": "array",
          "description": "The attribute columns specifies the meaning of the records that are being returned."
        },
        "values": {
          "items": {
            "type": "object"
          },
          "type": "array",
          "description": "The attribute values contains the actual data in the form of a JSON array. Each entry in the array contains a nested JSON array which represents statistical data for a single location or area (depending on the granularity of the city layer that is being queried). The statistical data is sorted according to the order that was specified by the columns attribute. As such, for the example shown, each entry is structured as follows:<ul><li>A <strong>geohash</strong> indicating the location or area for which the data applies</li><li>The <strong>mean</strong> of all measured values for the specified metric that were recorded at this location (in the requested timeframe).</li><li>The <strong>minimum</strong> of all measured values for the specified metric that were recorded at this location (in the requested timeframe).</li><li>The <strong>maximum</strong> of all measured values for the specified metric that were recorded at this location (in the requested timeframe).</li><li>The <strong>standard deviation</strong> of all measured values for the specified metric that were recorded at this location (in the requested timeframe).</li><li>The <strong>number</strong> of measured values for the specified metric that were recorded at this location (in the requested timeframe).</li></ul>"
        }
      },
      "required": [
        "name",
        "columns",
        "values"
      ]
    }
  }
}