swagger: "2.0"
schemes:
  - http
host: api.citycontext.com
basePath: /v1
info:
  description: "City Context provides a straightforward API to access UK Open Data: crime statistics, schools, demographics and more."
  title: City Context
  version: 1.0.0
  x-apisguru-categories:
    - open_data
  x-logo:
    url: https://api.apis.guru/v2/cache/logo/https_twitter.com_citycontext_profile_image.jpeg
  x-origin:
    - converter:
        url: https://github.com/lucybot/api-spec-converter
        version: 2.6.0
      format: swagger
      url: https://www.citycontext.com/swagger/spec.json
      version: "1.2"
  x-providerName: citycontext.com
produces:
  - application/json
securityDefinitions:
  user_key:
    description: City context user key
    in: query
    name: user_key
    type: apiKey
security:
  - user_key: []
tags:
  - description: Core City Context API
    name: citycontext
paths:
  "/@{lat},{lon}":
    get:
      operationId: byPoint
      parameters:
        - description: Latitude
          format: float
          in: path
          name: lat
          required: true
          type: number
        - description: Longitude
          format: float
          in: path
          name: lon
          required: true
          type: number
        - description: Search radius for schools, in metres, between 100 and 4000
          in: query
          name: school_search_radius
          required: false
          type: integer
        - description: Search radius for parks, in metres, between 100 and 2000
          in: query
          name: park_search_radius
          required: false
          type: integer
      responses:
        "200":
          description: No response was specified
          schema:
            $ref: "#/definitions/PointInfo"
      summary: Query by coordinates (SRID 4326 - decimal degrees)
      tags:
        - citycontext
  "/postcodes/{postcode}":
    get:
      operationId: byPostcode
      parameters:
        - description: Postcode
          in: path
          name: postcode
          required: true
          type: string
        - description: Search radius for schools, in metres, between 100 and 4000
          in: query
          name: school_search_radius
          required: false
          type: integer
        - description: Search radius for parks, in metres, between 100 and 2000
          in: query
          name: park_search_radius
          required: false
          type: integer
      responses:
        "200":
          description: No response was specified
          schema:
            $ref: "#/definitions/PointInfo"
      summary: Query by postcode
      tags:
        - citycontext
  /usage:
    get:
      operationId: usage
      parameters: []
      responses:
        "200":
          description: No response was specified
          schema:
            $ref: "#/definitions/Usage"
      summary: Get usage in current month
      tags:
        - citycontext
definitions:
  Latlon: {}
  Location:
    description: Latitude, Longitude and other info related to the given point
    properties:
      lat:
        format: float
        maximum: 85
        minimum: -85
        type: number
      lon:
        format: float
        maximum: 180
        minimum: -180
        type: number
      withinLondonCCZ:
        description: Boolean flag indicating whether this point is located within London's Congestion Charge zone
        type: boolean
    required:
      - lat
      - lon
    type: object
  PointInfo:
    description: Contextual information around a given point
    properties:
      location:
        $ref: "#/definitions/Location"
      lsoa:
        description: Statistics for lower layer super output areas (LSOA)
        properties:
          crimes:
            type: object
          name:
            type: string
          population:
            properties:
              allUsualResidents:
                type: integer
              communalEstablishmentResidents:
                type: integer
              householdResidents:
                type: integer
              households:
                type: integer
              personsPerHectare:
                type: integer
              personsPerHousehold:
                type: integer
            required:
              - allUsualResidents
              - householdResidents
              - communalEstablishmentResidents
              - households
              - personsPerHousehold
              - personsPerHectare
            type: object
        required:
          - name
        type: object
      parks:
        description: Parks within 1km of the point of interest, sorted by descending area
        items:
          properties:
            areaSqm:
              type: integer
            centroid:
              $ref: "#/definitions/Latlon"
            distanceMeters:
              type: integer
            name:
              type: string
          required:
            - distanceMeters
            - areaSqm
            - centroid
          type: object
        type: array
      schools:
        description: Schools within 1km of the point of interest, sorted by ascending distance from the POI
        items:
          properties:
            distanceMeters:
              type: integer
            lastInpectionUrl:
              description: URL to the last inspection report
              type: string
            lastInspectionDate:
              description: Date of the last Ofsted inspection
              format: date-time
              type: string
            leadershipAndManagement:
              description: Leadership and management grade in the last Ofsted report, from 1 (outstanding) to 4 (inadequate)
              maximum: 4
              minimum: 1
              type: integer
            location:
              $ref: "#/definitions/Latlon"
            overallEffectiveness:
              description: Overall effectiveness grade in the last Ofsted report, from 1 (outstanding) to 4 (inadequate)
              maximum: 4
              minimum: 1
              type: integer
            phase:
              type: string
            qualityOfTeaching:
              description: Quality of teaching grade in the last Ofsted report, from 1 (outstanding) to 4 (inadequate)
              maximum: 4
              minimum: 1
              type: integer
            schoolName:
              type: string
            typeOfEstablishment:
              type: string
            urn:
              description: Unique school identifier
              type: integer
          required:
            - urn
            - schoolName
            - typeOfEstablishment
            - location
            - lastInspectionDate
            - lastInpectionUrl
            - overallEffectiveness
            - leadershipAndManagement
            - qualityOfTeaching
            - phase
            - distanceMeters
          type: object
        type: array
    required:
      - location
      - parks
      - schools
  Usage:
    description: User plan monthly API quota and usage
    properties:
      allowance:
        type: integer
      period:
        type: string
      periodEnd:
        format: date-time
        type: string
      periodStart:
        format: date-time
        type: string
      plan:
        type: string
      usage:
        type: integer
    required:
      - usage
      - period
      - plan
      - periodStart
      - periodEnd
