swagger: "2.0"
schemes:
  - https
host: developer.o2.cz
basePath: /sociodemo/sandbox/api
info:
  contact:
    name: libertyapi@o2.cz
  description: Socio-demo API can be used to obtain time-aggregated data representing groups of people on the given location in the Czech Republic. Having a location, the API can return count of people belonging to age group or gender aggregated by hours. The socio-demo data is based on presence of mobile stations in O2 mobile network.
  license:
    name: O2 Czech Republic a.s.
    url: https://developer.o2.cz/portal/vop
  title: Socio-demo API
  version: 1.2.0
  x-apisguru-categories:
    - telecom
  x-logo:
    backgroundColor: "#FFFFFF"
    url: https://pbs.twimg.com/profile_images/443742048365985792/Zech6Z-m_400x400.png
  x-origin:
    - format: swagger
      url: https://developer.o2.cz/sociodemo/sandbox/api/swagger.json
      version: "2.0"
  x-providerName: o2.cz
  x-serviceName: sociodemo
tags:
  - name: info
  - name: sociodemo
paths:
  "/age/{location}":
    get:
      description: Get count of people in a given location and an hour, aggregated by age.
      operationId: age
      parameters:
        - description: basic residential unit
          in: path
          name: location
          required: true
          type: string
          x-example: "127752"
        - description: "age-group specification (1: 8-18, 2: 19-25, 3: 26-35, 4: 36-55, 5: 56+)"
          in: query
          name: ageGroup
          required: true
          type: string
          x-example: "2"
        - description: occurence type in the basic residential unit (1 - transit, 2 - visit)
          in: query
          name: occurenceType
          required: true
          type: string
          x-example: "1"
        - description: time interval for the count aggregation (from 0 to 23)
          in: query
          name: hour
          required: true
          type: string
          x-example: "10"
      produces:
        - application/json
      responses:
        "200":
          description: Response with the requested content.
          schema:
            $ref: "#/definitions/CountResult"
        "204":
          description: The request is valid, but the platform is not able to serve the data. The reason may be restriction (e.g. differential privacy) or no data were found.
        "400":
          description: Invalid request provided, missing or invalid parameter.
          schema:
            $ref: "#/definitions/ErrorResult"
        "500":
          description: Internal server error.
          schema:
            $ref: "#/definitions/ErrorResult"
      summary: Presence in a location aggregated by age
      tags:
        - sociodemo
  "/gender/{location}":
    get:
      description: Get count of people in a given location and an hour, aggregated by gender.
      operationId: gender
      parameters:
        - description: basic residential unit
          in: path
          name: location
          required: true
          type: string
          x-example: "127752"
        - description: gender specification (1 - male, 2 - female)
          in: query
          name: g
          required: true
          type: string
          x-example: "1"
        - description: occurence type in the basic residential unit (1 - transit, 2 - visit)
          in: query
          name: occurenceType
          required: true
          type: string
          x-example: "1"
        - description: time interval for the count aggregation (from 0 to 23)
          in: query
          name: hour
          required: true
          type: string
          x-example: "10"
      produces:
        - application/json
      responses:
        "200":
          description: Response with the requested content.
          schema:
            $ref: "#/definitions/CountResult"
        "204":
          description: The request is valid, but the platform is not able to serve the data. The reason may be restriction (e.g. differential privacy) or no data were found.
        "400":
          description: Invalid request provided, missing or invalid parameter.
          schema:
            $ref: "#/definitions/ErrorResult"
        "500":
          description: Internal server error.
          schema:
            $ref: "#/definitions/ErrorResult"
      summary: Presence in a location aggregated by gender
      tags:
        - sociodemo
  /info:
    get:
      consumes:
        - application/json
      description: ""
      operationId: getInfo
      parameters: []
      produces:
        - application/json
      responses:
        "200":
          description: Response with the requested content.
          schema:
            $ref: "#/definitions/InfoResult"
      summary: Information about versions of application and data.
      tags:
        - info
definitions:
  CountResult:
    description: Response with the result
    properties:
      count:
        description: Final count as the result of the request
        example: "62984"
        type: string
    type: object
  ErrorResult:
    description: Response with error message
    properties:
      message:
        description: Error response message content
        example: Error message example.
        type: string
    type: object
  InfoResult:
    description: Response to the info request
    properties:
      appName:
        description: Application name
        example: Mobility API Frontend
        type: string
      appVendor:
        description: Application vendor
        example: O2 Czech Republic a.s.
        type: string
      appVersion:
        description: Application version
        example: 1.0-M6-SNAPSHOT
        type: string
      backendAppName:
        description: Backend application name
        example: Mobility API Backend
        type: string
      backendAppVendor:
        description: Backend application vendor
        example: O2 Czech Republic a.s.
        type: string
      backendAppVersion:
        description: Backend application version
        example: 1.0-M6-SNAPSHOT
        type: string
      backendDataFrom:
        description: For which day are data valid
        example: 2017-07-31
        type: string
    type: object
