unicef/magicbox-open-api

View on GitHub
api/swagger/swagger.yaml

Summary

Maintainability
Test Coverage
swagger: "2.0"
info:
  version: "0.0.1"
  title: Welcome to The Magic Box Open API!
  description: "
<p>
This API serves information used by the data science team at the Office of Innovation at UNICEF.
</p>
<p>
For detailed instructions on how to use this API, please read this <a href='https://medium.com/@mikefabrikant/the-magic-box-wiki-a69e20a1dcfe'>wiki</a>.
</p>
<br/><br/>
  <u>Currently available</u>:

<p>
<ul>
  <li>
    Case data from <a href=http://www.paho.org/hq/index.php?option=com_content&view=article&id=12390&Itemid=42090&lang=en>Paho</a>
  </li>
  <li>
    Population from <a href='http://worldpop.org.uk'>worldpop</a>
  </li>
  <li>
    Mosquito prevalence -- Special thanks to the authors of <a href=https://elifesciences.org/articles/08347>The global distribution of the arbovirus vectors Aedes aegypti and Ae. albopictus</a>
  </li>
</ul>
</p>

<p>
You can clone and install the <a href='https://github.com/unicef/magicbox-open-api/'>Magic Box API</a> locally, it comes with sample data.  If you would like to generate the same data sets we serve, please go to the the <a href='https://github.com/unicef/magicbox/wiki'>Magic Box Wiki</a>.
</p>
<p>
  Most data comes with an admin ID, which is explained <a href='https://github.com/unicef/magicbox-open-api#what-does-this-mean'>here</a>. We will provide the option to request geojson with that data shortly.
</p>
"

# during dev, should point to your local machine
host: magicbox-open-api.azurewebsites.net
# basePath prefixes all resource paths
basePath: /api/
tags:
- name: "Population"
  # description: "worldpop.org aggregated by gadm2-8 shapefiles"
- name: "Mosquito"
- name: "Cases"
- name: "Mobility"
- name: "Access Control"
- name: 'Schools'
schemes:
  # tip: remove http to make production-grade
  - http
  - https
# format of bodies a client can send (Content-Type)
consumes:
  - application/json
  - application/x-www-form-urlencoded
# format of the responses to the client (Accepts)
produces:
  - application/json
  - text/html
securityDefinitions:
  Bearer:
      type: apiKey
      name: Token
      in: header

x-volos-resources:
  #Defines our cache
  cache:
      name: magic-box-cache
      provider: volos-cache-memory
      options:
        ttl: 90000000
        maxEntries: 10000

paths:
  /v1/mobility/countries:
    x-swagger-router-controller: general
    get:
      tags:
        - 'Mobility'
      description: Returns list of countries for which we have mobility data. Each list entry also has the data provider's name ("source") and the file series name ("series").
      summary: abw, afg...
      # used as the method name of the controller
      operationId: getCountriesAndSourceData
      responses:
        "200":
          description: Success
          examples:
            application/json: {
                                "key": "mobility",
                                "properties": [
                                    {
                                    "country": 'col',
                                    "source": 'acme',
                                    "series": 'santiblanko'
                                    }
                                ]
                              }
          schema:
            # a pointer to a definition
            $ref: "#/definitions/ValueResponse"
        # responses many fall through to errors
        default:
          description: Error
          schema:
            $ref: "#/definitions/ErrorResponse"
  /v1/mobility/sources:
    # binds a127 app logic to a route
    x-swagger-router-controller: general
    get:
      tags:
        - 'Mobility'
      description: Returns list of sources for mobility
      summary: amadeus, telefonica...
      # used as the method name of the controller
      operationId: getProperties
      responses:
        "200":
          description: Success
          examples:
            application/json: {
                                "key": "mosquito",
                                "properties": [
                                    "amadeus",
                                    "telefonica"
                                ]
                              }
          schema:
            # a pointer to a definition
            $ref: "#/definitions/ValueResponse"
        # responses may fall through to errors
        default:
          description: Error
          schema:
            $ref: "#/definitions/ErrorResponse"
  /v1/mobility/sources/{source}/series:
    # binds a127 app logic to a route
    x-swagger-router-controller: general
    get:
      tags:
        - 'Mobility'
      description: Returns list shapefile series
      parameters:
        - name: source
          type: string
          in: path
          required: true
       # used as the method n
      summary: gadm2-8, santiblanko...
      # used as the method name of the controller
      operationId: getProperties
      responses:
        "200":
          description: Success
          examples:
            application/json: {
                                "key": "mobility",
                                "properties": [
                                    "gadm2-8",
                                    "santiblanko"
                                ]
                              }
          schema:
            # a pointer to a definition
            $ref: "#/definitions/ValueResponse"
        # responses may fall through to errors
        default:
          description: Error
          schema:
            $ref: "#/definitions/ErrorResponse"
  /v1/mobility/sources/{source}/series/{series}/countries:
    # binds a127 app logic to a route
    x-swagger-router-controller: general
    get:
      tags:
        - 'Mobility'
      description: Returns list dates with mobility for specified source, shapefile set, country
      parameters:
        - name: source
          type: string
          in: path
          required: true
        - name: series
          type: string
          in: path
          required: true
       # used as the method n
      summary: gadm2-8, santiblanko...
      # used as the method name of the controller
      operationId: getProperties
      responses:
        "200":
          description: Success
          examples:
            application/json: {
                                "key": "mobility",
                                "properties": [
                                  "col"
                                ]
                              }
          schema:
            # a pointer to a definition
            $ref: "#/definitions/ValueResponse"
        # responses may fall through to errors
        default:
          description: Error
          schema:
            $ref: "#/definitions/ErrorResponse"
  /v1/mobility/sources/{source}/series/{series}/countries/{country}:
    # binds a127 app logic to a route
    x-swagger-router-controller: general
    get:
      tags:
        - 'Mobility'
      description: Returns list dates with mobility for specified source, shapefile set, country
      parameters:
        - name: source
          type: string
          in: path
          required: true
        - name: series
          type: string
          in: path
          required: true
        - name: country
          type: string
          in: path
          required: true
       # used as the method n
      summary: gadm2-8, santiblanko...
      # used as the method name of the controller
      operationId: getProperties
      responses:
        "200":
          description: Success
          examples:
            application/json: {
                                "key": "mobility",
                                "properties": [
                                  "2015-02-01.csv",
                                  "2015-02-02.csv",
                                  "2015-02-03.csv"
                                ]
                              }
          schema:
            # a pointer to a definition
            $ref: "#/definitions/ValueResponse"
        # responses may fall through to errors
        default:
          description: Error
          schema:
            $ref: "#/definitions/ErrorResponse"
  /v1/mobility/sources/{source}/series/{series}/countries/{country}/{csv}:
    # binds a127 app logic to a route
    x-swagger-router-controller: general
    get:
      tags:
        - 'Mobility'
      description: Returns list dates with mobility for specified source, shapefile set, country
      parameters:
        - name: source
          type: string
          in: path
          required: true
        - name: series
          type: string
          in: path
          required: true
        - name: country
          type: string
          in: path
          required: true
        - name: csv
          type: string
          in: path
          required: true
       # used as the method n
      summary: gadm2-8, santiblanko...
      # used as the method name of the controller
      operationId: getProperties
      responses:
        "200":
          description: Success
          examples:
            application/json: {
                                "key": "mosquito",
                                "properties": [
                                    "gadm2-8",
                                    "santiblanko"
                                ]
                              }
          schema:
            # a pointer to a definition
            $ref: "#/definitions/ValueResponse"
        # responses may fall through to errors
        default:
          description: Error
          schema:
            $ref: "#/definitions/ErrorResponse"

  /v1/mosquito/kinds/:
    # binds a127 app logic to a route
    x-swagger-router-controller: general
    get:
      tags:
        - 'Mosquito'
      description: Returns list of mosquito kinds for which data is available
      summary: aegypti / albopictus
      # used as the method name of the controller
      operationId: getProperties
      responses:
        "200":
          description: Success
          examples:
            application/json: {
                                "key": "mosquito",
                                "properties": [
                                    "aegypti",
                                    "albopictus"
                                ]
                              }
          schema:
            # a pointer to a definition
            $ref: "#/definitions/ValueResponse"
        # responses may fall through to errors
        default:
          description: Error
          schema:
            $ref: "#/definitions/ErrorResponse"
  /v1/mosquito/kinds/{kind}:
    # binds a127 app logic to a route
    x-swagger-router-controller: general
    get:
      tags:
        - 'Mosquito'
      description: Returns mosquito prevelence metadata for all countries - arg, bra, col...etc. Data sourced from, The global distribution of the arbovirus vectors Aedes aegypti and Ae. albopictus, https://elifesciences.org/articles/08347
      summary: aegypti / albopictus
      parameters:
        - name: kind
          type: string
          in: path
          required: true
      # used as the method name of the controller
      operationId: getMosquito
      responses:
        "200":
          description: Success
          examples:
            application/json: {
                              "key": "mosquito",
                              "kind": "aegypti",
                              "source": "The global distribution of the arbovirus vectors Aedes aegypti and Ae. albopictus",
                              "source_url": "https://elifesciences.org/content/4/e08347",
                              "data": {
                                "abw": [
                                    {
                                    "country": "abw",
                                    "data_source": "simon_hay",
                                    "shapefile": "gadm2-8",
                                    "admin_level": "0",
                                    "sum": 0.92733,
                                    "sq_km": 70,
                                    "density": 0.013247571428571428,
                                    "raster": "aegypti"
                                    }
                                ]
                              }
                            }
          schema:
            # a pointer to a definition
            $ref: "#/definitions/MosquitoKindResponse"
        # responses may fall through to errors
        default:
          description: Error
          schema:
            $ref: "#/definitions/ErrorResponse"
  /v1/mosquito/kinds/{kind}/countries/:
     # binds a127 app logic to a route
    x-swagger-router-controller: general
    get:
      tags:
        - 'Mosquito'
      description: Returns list of countries for which data regarding specified kind of mosquito is available
      parameters:
        - name: kind
          type: string
          in: path
          required: true
       # used as the method name of the controller
      operationId: getProperties
      responses:
        "200":
          description: Success
          examples:
            application/json: {
                              "key": "mosquito_aegypti",
                              "properties": [
                                      "abw",
                                      "afg",
                                      "ago"
                              ]
                            }
          schema:
             # a pointer to a definition
            $ref: "#/definitions/ValueResponse"
         # responses may fall through to errors
        default:
          description: Error
          schema:
            $ref: "#/definitions/ErrorResponse"
  /v1/mosquito/kinds/{kind}/countries/{country}:
     # binds a127 app logic to a route
    x-swagger-router-controller: general
    get:
      tags:
        - 'Mosquito'
      description: Returns all metadata regarding mosquito prevalence for requested country - arg, bra, col...etc.  Data sourced from, The global distribution of the arbovirus vectors Aedes aegypti and Ae. albopictus, https://elifesciences.org/articles/08347
      parameters:
        - name: kind
          type: string
          in: path
          required: true
        - name: country
          type: string
          in: path
          required: true
       # used as the method name of the controller
      operationId: getMosquito
      responses:
        "200":
          description: Success
          examples:
            application/json: {
                          "key": "mosquito",
                          "kind": "aegypti",
                          "source": "The global distribution of the arbovirus vectors Aedes aegypti and Ae. albopictus",
                          "source_url": "https://elifesciences.org/content/4/e08347",
                          "data": {
                          "raster": "aegypti",
                          "source": "simon_hay",
                          "population": [
                                  {
                                  "admin_id": "afg_1_16_170_gadm2-8",
                                  "value": 0.134451949145065,
                                  "ID_0": 1,
                                  "ISO": "AFG",
                                  "NAME_0": "Afghanistan",
                                  "ID_1": 16,
                                  "NAME_1": "Kapisa",
                                  "ID_2": 170,
                                  "NAME_2": "Nijrab",
                                  "HASC_2": "AF.KP.NI",
                                  "CCN_2": 0,
                                  "CCA_2": null,
                                  "TYPE_2": "Wuleswali",
                                  "ENGTYPE_2": "District",
                                  "NL_NAME_2": null,
                                  "VARNAME_2": null
                                  }
                                ]
                              }
                            }
          schema:
             # a pointer to a definition
            $ref: "#/definitions/MosquitoCountryResponse"
         # responses may fall through to errors
        default:
          description: Error
          schema:
            $ref: "#/definitions/ErrorResponse"
  # #/population/{format}/{country}:
  # /v1/population:
  #   # binds a127 app logic to a route
  #   x-swagger-router-controller: general
  #   get:
  #     tags:
  #       - 'Population'
  #     description: Returns all countries for which we have population. For population worldpop id used as default source
  #     # used as the method name of the controller
  #     operationId: getPopulation
  #     security:
  #       - Bearer: []
  #     x-security-scopes:
  #       - user
  #     responses:
  #       "200":
  #         description: Success
  #         examples:
  #           application/json: { "data_kind": "population",
  #                               "data": {
  #                                 "afg": [
  #                                       { "country": "afg",
  #                                       "data_source": "worldpop",
  #                                       "shapefile_set": "gadm2-8",
  #                                       "admin_level": "2",
  #                                       "sum": 45155184,
  #                                       "sq_km": 248596,
  #                                       "density": 181.64083090637018,
  #                                       "raster": "popmap15adj" }
  #                                 ]
  #                               }
  #                             }
  #         schema:
  #           # a pointer to a definition
  #           $ref: "#/definitions/PopulationResponse"
  #       # responses may fall through to errors
  #       "403":
  #         description: Access denied
  #         schema:
  #           $ref: "#/definitions/AccessErrorResponse"
  #       default:
  #         description: Error
  #         schema:
  #           $ref: "#/definitions/ErrorResponse"
  # /v1/population/sources/:
  #   # binds a127 app logic to a route
  #   x-swagger-router-controller: general
  #   get:
  #     tags:
  #       - 'Population'
  #     description: Returns list of different sources from which population data is available
  #     # used as the method name of the controller
  #     operationId: getProperties
  #     responses:
  #       "200":
  #         description: Success
  #         examples:
  #           application/json: {
  #                         "key": "population",
  #                         "properties": [
  #                             "worldbank",
  #                             "worldpop"
  #                           ]
  #                         }
  #         schema:
  #           # a pointer to a definition
  #           $ref: "#/definitions/ValueResponse"
  #       # responses may fall through to errors
  #       default:
  #         description: Error
  #         schema:
  #           $ref: "#/definitions/ErrorResponse"
  # /v1/population/sources/{source}:
  #   # binds a127 app logic to a route
  #   x-swagger-router-controller: general
  #   get:
  #     tags:
  #       - 'Population'
  #     description: Returns all countries for which we have population from specified source
  #     parameters:
  #       - name: source
  #         type: string
  #         in: path
  #         required: true
  #     # used as the method name of the controller
  #     operationId: getPopulation
  #     responses:
  #       "200":
  #         description: Success
  #         examples:
  #           application/json: { "data_kind": "population",
  #                               "data": {
  #                                 "afg": [
  #                                       { "country": "afg",
  #                                       "data_source": "worldpop",
  #                                       "shapefile_set": "gadm2-8",
  #                                       "admin_level": "2",
  #                                       "sum": 45155184,
  #                                       "sq_km": 248596,
  #                                       "density": 181.64083090637018,
  #                                       "raster": "popmap15adj" }
  #                                 ]
  #                               }
  #                             }
  #         schema:
  #           # a pointer to a definition
  #           $ref: "#/definitions/PopulationResponse"
  #       # responses may fall through to errors
  #       default:
  #         description: Error
  #         schema:
  #           $ref: "#/definitions/ErrorResponse"
  # # #/population/{format}/{country}:
  # /v1/population:
  #   # binds a127 app logic to a route
  #   x-swagger-router-controller: general
  #   x-volos-apply:
  #     # Applies the cache to our endpoint
  #     cache:
  #       # Gets the cache name by calling
  #       # cacheKey() in /helpers/volos.js
  #       key:
  #           helper: volos
  #           function: cachePopulation
  #   get:
  #     tags:
  #       - 'Population'
  #     summary: World Bank population figures per country
  #     description: Returns population figures published by the World Bank.
  #     # used as the method name of the controller
  #     operationId: getPopulation
  #     responses:
  #       "200":
  #         description: Success
  #         examples:
  #           application/json: { "data_kind": "population",
  #                               "data": {
  #                                 "afg": [
  #                                       { "country": "afg",
  #                                       "data_source": "worldpop",
  #                                       "shapefile_set": "gadm2-8",
  #                                       "admin_level": "2",
  #                                       "sum": 45155184,
  #                                       "sq_km": 248596,
  #                                       "density": 181.64083090637018,
  #                                       "raster": "popmap15adj" }
  #                                 ]
  #                               }
  #                             }
  #         schema:
  #           # a pointer to a definition
  #           $ref: "#/definitions/PopulationResponse"
  #       # responses may fall through to errors
  #       default:
  #         description: Error
  #         schema:
  #           $ref: "#/definitions/ErrorResponse"
  # /v1/population/sources/:
  #   # binds a127 app logic to a route
  #   x-swagger-router-controller: general
  #   x-volos-apply:
  #     # Applies the cache to our endpoint
  #     cache:
  #       # Gets the cache name by calling
  #       # cacheKey() in /helpers/volos.js
  #       key:
  #           helper: volos
  #           function: cachePopulationProperties
  #   get:
  #     tags:
  #       - 'Population'
  #     summary: worldbank - admin 0, worldpop - highest admin level available from worldpop.org
  #     description: Returns list of different sources from which population data is available
  #     # used as the method name of the controller
  #     operationId: getProperties
  #     responses:
  #       "200":
  #         description: Success
  #         examples:
  #           application/json: {
  #                         "key": "population",
  #                         "properties": [
  #                             "worldbank",
  #                             "worldpop"
  #                           ]
  #                         }
  #         schema:
  #           # a pointer to a definition
  #           $ref: "#/definitions/ValueResponse"
  #       # responses may fall through to errors
  #       default:
  #         description: Error
  #         schema:
  #           $ref: "#/definitions/ErrorResponse"
  # /v1/population/sources/{source}:
  #   # binds a127 app logic to a route
  #   x-swagger-router-controller: general
  #   x-volos-apply:
  #     # Applies the cache to our endpoint
  #     cache:
  #       # Gets the cache name by calling
  #       # cacheKey() in /helpers/volos.js
  #       key:
  #           helper: volos
  #           function: cachePopulation
  #   get:
  #     tags:
  #       - 'Population'
  #     description: Returns all countries for which we have population from specified source
  #     parameters:
  #       - name: source
  #         type: string
  #         in: path
  #         required: true
  #     # used as the method name of the controller
  #     operationId: getPopulation
  #     responses:
  #       "200":
  #         description: Success
  #         examples:
  #           application/json: { "data_kind": "population",
  #                               "data": {
  #                                 "afg": [
  #                                       { "country": "afg",
  #                                       "data_source": "worldpop",
  #                                       "shapefile_set": "gadm2-8",
  #                                       "admin_level": "2",
  #                                       "sum": 45155184,
  #                                       "sq_km": 248596,
  #                                       "density": 181.64083090637018,
  #                                       "raster": "popmap15adj" }
  #                                 ]
  #                               }
  #                             }
  #         schema:
  #           # a pointer to a definition
  #           $ref: "#/definitions/PopulationResponse"
  #       # responses may fall through to errors
  #       default:
  #         description: Error
  #         schema:
  #           $ref: "#/definitions/ErrorResponse"
  /v1/population/countries/:
    # binds a127 app logic to a route
    x-swagger-router-controller: general
    get:
      tags:
        - 'Population'
      description: Returns list of all the countries for which we have population data. For this worldpop is used as default source.
      # used as the method name of the controller
      operationId: getProperties
      responses:
        "200":
          description: Success
          examples:
            application/json: {
                            "key": "population_worldpop",
                            "properties": [
                                    "afg",
                                    "ago",
                                    "arg",
                                    "arm"
                                ]
                            }
          schema:
            # a pointer to a definition
            $ref: "#/definitions/ValueResponse"
        # responses may fall through to errors
        default:
          description: Error
          schema:
            $ref: "#/definitions/ErrorResponse"
  # # #/population/{format}/{country}:
  /v1/population/countries/{country}:
    # binds a127 app logic to a route
    x-swagger-router-controller: general
    get:
      tags:
        - 'Population'
      description: Returns admin level population at highest admin level available by gadm.org
      parameters:
        - name: country
          type: string
          in: path
          required: true
      # used as the method name of the controller
      operationId: getPopulation
      responses:
        "200":
          description: Success
          examples:
            application/json: {
                            "key": "population",
                            "source": "worldpop",
                            "data": {
                            "raster": "popmap15adj",
                            "source": "worldpop",
                            "population": [
                                      {
                                      "admin_id": "afg_1_12_129_worldpop",
                                      "value": 74459.9892636929,
                                      "ID_0": 1,
                                      "ISO": "AFG",
                                      "NAME_0": "Afghanistan",
                                      "ID_1": 12,
                                      "NAME_1": "Hirat",
                                      "ID_2": 129,
                                      "NAME_2": "Zinda Jan",
                                      "HASC_2": "AF.HR.ZJ",
                                      "CCN_2": 0,
                                      "CCA_2": null,
                                      "TYPE_2": "Wuleswali",
                                      "ENGTYPE_2": "District",
                                      "NL_NAME_2": null,
                                      "VARNAME_2": null
                                      }
                                  ]
                                }
                            }
          schema:
            # a pointer to a definition
            $ref: "#/definitions/PopulationCountryResponse"
        # responses may fall through to errors
        default:
          description: Error
          schema:
            $ref: "#/definitions/ErrorResponse"
  # /v1/population/sources/{source}/countries/:
  #   # binds a127 app logic to a route
  #   x-swagger-router-controller: general
  #   x-volos-apply:
  #     # Applies the cache to our endpoint
  #     cache:
  #       # Gets the cache name by calling
  #       # cacheKey() in /helpers/volos.js
  #       key:
  #           helper: volos
  #           function: cachePopulationProperties
  #   get:
  #     tags:
  #       - 'Population'
  #     description: Returns list of all the countries for which we have population data from specified source.
  #     summary: arg, bra, col
  #     parameters:
  #       - name: source
  #         type: string
  #         in: path
  #         required: true
  #     # used as the method name of the controller
  #     operationId: getProperties
  #     responses:
  #       "200":
  #         description: Success
  #         examples:
  #           application/json: {
  #                           "key": "population_worldpop",
  #                           "properties": [
  #                                   "afg",
  #                                   "ago",
  #                                   "arg",
  #                                   "arm"
  #                               ]
  #                           }
  #         schema:
  #           # a pointer to a definition
  #           $ref: "#/definitions/ValueResponse"
  #       # responses may fall through to errors
  #       default:
  #         description: Error
  #         schema:
  #           $ref: "#/definitions/ErrorResponse"
  # /v1/population/sources/{source}/countries/{country}:
  #   # binds a127 app logic to a route
  #   x-swagger-router-controller: general
  #   x-volos-apply:
  #     # Applies the cache to our endpoint
  #     cache:
  #       # Gets the cache name by calling
  #       # cacheKey() in /helpers/volos.js
  #       key:
  #           helper: volos
  #           function: cachePopulation
  #   get:
  #     tags:
  #       - 'Population'
  #     description: Returns all population metadata for requested country - arg, bra, col...etc.
  #     summary: arg, bra, col
  #     parameters:
  #       - name: source
  #         type: string
  #         in: path
  #         required: true
  #       - name: country
  #         type: string
  #         in: path
  #         required: true
  #     # used as the method name of the controller
  #     operationId: getPopulation
  #     responses:
  #       "200":
  #         description: Success
  #         examples:
  #           application/json: {
  #                           "key": "population",
  #                           "source": "worldpop",
  #                           "data": {
  #                           "raster": "popmap15adj",
  #                           "source": "worldpop",
  #                           "population": [
  #                                     {
  #                                     "admin_id": "afg_1_12_129_worldpop",
  #                                     "value": 74459.9892636929,
  #                                     "ID_0": 1,
  #                                     "ISO": "AFG",
  #                                     "NAME_0": "Afghanistan",
  #                                     "ID_1": 12,
  #                                     "NAME_1": "Hirat",
  #                                     "ID_2": 129,
  #                                     "NAME_2": "Zinda Jan",
  #                                     "HASC_2": "AF.HR.ZJ",
  #                                     "CCN_2": 0,
  #                                     "CCA_2": null,
  #                                     "TYPE_2": "Wuleswali",
  #                                     "ENGTYPE_2": "District",
  #                                     "NL_NAME_2": null,
  #                                     "VARNAME_2": null
  #                                     }
  #                                 ]
  #                               }
  #                           }
  #         schema:
  #           # a pointer to a definition
  #           $ref: "#/definitions/PopulationCountryResponse"
  #       # responses may fall through to errors
  #       default:
  #         description: Error
  #         schema:
  #           $ref: "#/definitions/ErrorResponse"
  /v1/cases/kinds/:
    # binds a127 app logic to a route
    x-swagger-router-controller: general
    get:
      tags:
        - 'Cases'
      description: Returns list of epidemics for which case data is available.
      summary: zika/epi
      operationId: getProperties
      responses:
        "200":
          description: Success
          examples:
            application/json: {
                          "key": "cases",
                          "properties": [
                              "zika"
                            ]
                          }
          schema:
            # a pointer to a definition
            $ref: "#/definitions/ValueResponse"
        # responses may fall through to errors
        default:
          description: Error
          schema:
            $ref: "#/definitions/ErrorResponse"
  /v1/cases/kinds/{kind}/weekTypes/:
    # binds a127 app logic to a route
    x-swagger-router-controller: general
    get:
      tags:
        - 'Cases'
      description: Returns list of week-types for specified epidemic.
      summary: zika/epi
      parameters:
        - name: kind
          type: string
          in: path
          required: true
      operationId: getProperties
      responses:
        "200":
          description: Success
          examples:
            application/json: {
                        "key": "cases_zika",
                        "properties": [
                                "epi",
                                "iso"
                            ]
                        }
          schema:
            # a pointer to a definition
            $ref: "#/definitions/ValueResponse"
        # responses may fall through to errors
        default:
          description: Error
          schema:
            $ref: "#/definitions/ErrorResponse"
  /v1/cases/kinds/{kind}/weekTypes/{weekType}/weeks:
    # binds a127 app logic to a route
    x-swagger-router-controller: general
    get:
      tags:
        - 'Cases'
      description: Returns list of weeks for which requested data is available. List has first day of week.
      summary: zika/epi
      parameters:
        - name: kind
          type: string
          in: path
          required: true
        - name: weekType
          type: string
          in: path
          required: true
      operationId: getProperties
      responses:
        "200":
          description: Success
          examples:
            application/json: {
                          "key": "cases_zika_epi",
                          "properties": [
                                  "2016-11-17",
                                  "2016-11-23",
                                  "2016-11-30"
                              ]
                          }
          schema:
            # a pointer to a definition
            $ref: "#/definitions/ValueResponse"
        # responses may fall through to errors
        default:
          description: Error
          schema:
            $ref: "#/definitions/ErrorResponse"
  /v1/cases/kinds/{kind}/weekTypes/{weekType}:
    # binds a127 app logic to a route
    x-swagger-router-controller: general
    get:
      tags:
        - 'Cases'
      description: Returns JSON with metadata regarding cases for specified kind. Data sourced from Paho, http://www.paho.org/hq/index.php?option=com_content&view=article&id=12390&Itemid=42090&lang=en
      summary: zika/epi
      parameters:
        - name: kind
          type: string
          in: path
          required: true
        - name: weekType
          type: string
          in: path
          required: true
      operationId: getCases
      responses:
        "200":
          description: Success
          examples:
            application/json: { "cases": {
                                  "2016-11-17": {
                                    "can": {
                                        "country": "Canada",
                                        "autochthonous_cases_suspected": 0,
                                        "autochthonous_cases_confirmed": 0,
                                        "imported_cases": 374,
                                        "incidence_rate": 0,
                                        "deaths": 0,
                                        "confirmed_congenital": 0,
                                        "population_x_1k": 36286,
                                        "congenital_suspected": 0,
                                        "congenital_probable": 0,
                                        "gbs_total": 0,
                                        "gbs_confirmed": 0
                                    }
                                  }
                                }
                              }
          schema:
            # a pointer to a definition
            $ref: "#/definitions/casesResponse"
        # responses may fall through to errors
        default:
          description: Error
          schema:
            $ref: "#/definitions/ErrorResponse"
  /v1/cases/kinds/{kind}/weekTypes/{weekType}/week/{date}:
    # binds a127 app logic to a route
    x-swagger-router-controller: general
    get:
      tags:
        - 'Cases'
      description: Returns JSON with metadata regarding zika cases
      parameters:
        - name: kind
          type: string
          in: path
          required: true
        - name: weekType
          type: string
          in: path
          required: true
        - name: date
          type: string
          in: path
          required: true
      operationId: getCases
      responses:
        "200":
          description: Success
          examples:
            application/json: { "cases": {
                                  "2016-11-17": {
                                    "can": {
                                        "country": "Canada",
                                        "autochthonous_cases_suspected": 0,
                                        "autochthonous_cases_confirmed": 0,
                                        "imported_cases": 374,
                                        "incidence_rate": 0,
                                        "deaths": 0,
                                        "confirmed_congenital": 0,
                                        "population_x_1k": 36286,
                                        "congenital_suspected": 0,
                                        "congenital_probable": 0,
                                        "gbs_total": 0,
                                        "gbs_confirmed": 0
                                    }
                                  }
                                }
                              }
          schema:
            # a pointer to a definition
            $ref: "#/definitions/casesResponse"
        # responses may fall through to errors
        default:
          description: Error
          schema:
            $ref: "#/definitions/ErrorResponse"
  /v1/getAccess:
    x-swagger-router-controller: general
    get:
      tags:
        - 'Access Control'
      description: Auth0 try
      operationId: getToken
      responses:
        "200":
          description: Success
          examples:
            application/json: { "cases": {
                                  "2016-11-17": {
                                    "can": {
                                        "country": "Canada",
                                        "autochthonous_cases_suspected": 0,
                                        "autochthonous_cases_confirmed": 0,
                                        "imported_cases": 374,
                                        "incidence_rate": 0,
                                        "deaths": 0,
                                        "confirmed_congenital": 0,
                                        "population_x_1k": 36286,
                                        "congenital_suspected": 0,
                                        "congenital_probable": 0,
                                        "gbs_total": 0,
                                        "gbs_confirmed": 0
                                    }
                                  }
                                }
                              }
          schema:
            # a pointer to a definition
            $ref: "#/definitions/casesResponse"
        # responses may fall through to errors
        default:
          description: Error
          schema:
            $ref: "#/definitions/ErrorResponse"
  /v1/token/:
    x-swagger-router-controller: general
    x-hide: true
    post:
      description: Auth0 get
      operationId: showToken
      parameters:
      - name: token
        in: body
        description: The pet JSON you want to post
        schema:
          type: string
        required: true
      responses:
        "200":
          description: Success
          examples:
            application/json: { "cases": {
                                  "2016-11-17": {
                                    "can": {
                                        "country": "Canada",
                                        "autochthonous_cases_suspected": 0,
                                        "autochthonous_cases_confirmed": 0,
                                        "imported_cases": 374,
                                        "incidence_rate": 0,
                                        "deaths": 0,
                                        "confirmed_congenital": 0,
                                        "population_x_1k": 36286,
                                        "congenital_suspected": 0,
                                        "congenital_probable": 0,
                                        "gbs_total": 0,
                                        "gbs_confirmed": 0
                                    }
                                  }
                                }
                              }
          schema:
            # a pointer to a definition
            $ref: "#/definitions/casesResponse"
        # responses may fall through to errors
        default:
          description: Error
          schema:
            $ref: "#/definitions/ErrorResponse"
  /v1/get_refresh_token/:
    x-swagger-router-controller: general
    x-hide: true
    get:
      description: Auth0 get
      operationId: getRefreshToken
      parameters:
      - name: token
        in: body
        description: The pet JSON you want to post
        schema:
          type: string
        required: true
      responses:
        "200":
          description: Success
          examples:
            application/json: { "cases": {
                                  "2016-11-17": {
                                    "can": {
                                        "country": "Canada",
                                        "autochthonous_cases_suspected": 0,
                                        "autochthonous_cases_confirmed": 0,
                                        "imported_cases": 374,
                                        "incidence_rate": 0,
                                        "deaths": 0,
                                        "confirmed_congenital": 0,
                                        "population_x_1k": 36286,
                                        "congenital_suspected": 0,
                                        "congenital_probable": 0,
                                        "gbs_total": 0,
                                        "gbs_confirmed": 0
                                    }
                                  }
                                }
                              }
          schema:
            # a pointer to a definition
            $ref: "#/definitions/casesResponse"
        # responses may fall through to errors
        default:
          description: Error
          schema:
            $ref: "#/definitions/ErrorResponse"
  /v1/refresh_token/{refresh_token}:
    x-swagger-router-controller: general
    x-hide: true
    get:
      description: Auth0 get
      operationId: refreshToken
      parameters:
      - name: refresh_token
        type: string
        in: path
        required: true
      responses:
        "200":
          description: Success
          examples:
            application/json: { "cases": {
                                  "2016-11-17": {
                                    "can": {
                                        "country": "Canada",
                                        "autochthonous_cases_suspected": 0,
                                        "autochthonous_cases_confirmed": 0,
                                        "imported_cases": 374,
                                        "incidence_rate": 0,
                                        "deaths": 0,
                                        "confirmed_congenital": 0,
                                        "population_x_1k": 36286,
                                        "congenital_suspected": 0,
                                        "congenital_probable": 0,
                                        "gbs_total": 0,
                                        "gbs_confirmed": 0
                                    }
                                  }
                                }
                              }
          schema:
            # a pointer to a definition
            $ref: "#/definitions/casesResponse"
        # responses may fall through to errors
        default:
          description: Error
          schema:
            $ref: "#/definitions/ErrorResponse"
  /v1/schools/countries/:
    # binds a127 app logic to a route
    x-swagger-router-controller: general
    get:
      tags:
        - 'Schools'
      description: Returns list of countries with for which we have school data
      summary: 'List of countries with school data'
      # used as the method name of the controller
      operationId: getCountriesWithSchools
      responses:
        "200":
          description: Success
          examples:
            application/json: {
                            "key": "schools",
                            "properties": [
                                    "afg",
                                    "ago",
                                    "arg",
                                    "arm"
                                ]
                            }
          schema:
            # a pointer to a definition
            $ref: "#/definitions/ValueResponse"
        # responses may fall through to errors
        default:
          description: Error
          schema:
            $ref: "#/definitions/ErrorResponse"

  /v1/schools/countries/{country}:
    # binds a127 app logic to a route
    x-swagger-router-controller: general
    get:
      tags:
        - 'Schools'
      description: Returns list of weeks for which requested data is available. List has first day of week.
      summary: Schools in country
      parameters:
        - name: country
          type: string
          in: path
          required: true
        - name: queryString
          type: string
          in: query
          required: false
      operationId: getSchools
      security:
        - Bearer: []
      x-security-scopes:
        - proco
      responses:
        "200":
          description: Success
          schema:
            # a pointer to a definition
            $ref: "#/definitions/SchoolsResponse"
        # responses may fall through to errors
        default:
          description: Error
          schema:
            $ref: "#/definitions/ErrorResponse"
  /v1/schools/school/{school_id}:
    # binds a127 app logic to a route
    x-swagger-router-controller: general
    get:
      tags:
        - 'Schools'
      description: Returns SchoolResponse
      summary: School by ID
      parameters:
        - name: school_id
          type: string
          in: path
          required: true
        - name: queryString
          type: string
          in: query
          required: false
      operationId: getSchool
      security:
        - Bearer: []
      x-security-scopes:
        - proco
      responses:
        "200":
          description: Success
          schema:
            # a pointer to a definition
            $ref: "#/definitions/SchoolResponse"
        # responses may fall through to errors
        default:
          description: Error
          schema:
            $ref: "#/definitions/ErrorResponse"
  /swagger:
    x-swagger-pipe: swagger_raw
# complex objects have schema definitions
definitions:
  MosquitoKindResponse:
    required:
      - countries
    properties:
      countries:
        type: object
  PopulationResponse:
    required:
      - countries
    properties:
      countries:
        type: object
  PopulationCountryResponse:
    required:
       - country
       - source
       - raster
       - population
    properties:
      country:
        type: 'string'
      source:
        type: 'string'
      raster:
        type: 'string'
      population:
        type: object
  casesResponse:
    required:
      - kind
      - cases
    properties:
      kind:
        type: string
      cases:
        type: object
  MosquitoCountryResponse:
    required:
      - country
      - source
      - raster
      - mosquito_prevalence
    properties:
      country:
        type: 'string'
      source:
        type: 'string'
      raster:
        type: 'string'
      mosquito_prevalence:
        type: object
  ValueResponse:
    required:
      - key
      - properties
    properties:
      key:
        type: 'string'
      properties:
        type: object
  ErrorResponse:
    required:
      - message
    properties:
      message:
        type: object
  AccessErrorResponse:
    required:
      - message
    properties:
      message:
        type: string
  SchoolsResponse:
    required:
      - count
      - result
      - hasNext
    properties:
      count:
        type: string
      result:
        type: object
      hasNext:
        type: boolean
  SchoolResponse:
    required:
      - result
    properties:
      result:
        type: object