openapi.yaml

openapi: 3.0.3
info:
  title: "BNA REST API"
  description: "Provides a way to retrieve the BNA results programmatically."
  version: "1.0.0"
  contact:
    name: The BNA Mechanics team
    url: https://peopleforbikes.github.io/
servers:
  - url: "https://api.peopleforbikes.xyz"
    description: Staging API
  - url: "https://localhost:3000"
    description: Local development API
tags:
  - name: city
  - name: price
  - name: rating
paths:
  /ratings:
    get:
      operationId: getRatings
      summary: Get city rating summaries
      description: Get city rating summaries.
      tags:
        - rating
      responses:
        200:
          $ref: "#/components/responses/rating_summaries"
      parameters:
        - $ref: "#/components/parameters/page"
        - $ref: "#/components/parameters/page_size"
    post:
      operationId: postRatings
      summary: Create new city rating
      description: Create a new city rating
      tags:
        - rating
      requestBody:
        description: Create bna
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/bna_post"
      responses:
        201:
          $ref: "#/components/responses/rating"
        403:
          $ref: "#/components/responses/forbidden"
      security:
        - Authorize: []
  /ratings/analyses:
    get:
      operationId: getRatingsAnalyses
      summary: "Get the city rating analys details"
      description: "Get the city rating analys details"
      tags:
        - rating
      responses:
        200:
          $ref: "#/components/responses/analyses"
        403:
          $ref: "#/components/responses/forbidden"
      parameters:
        - $ref: "#/components/parameters/page"
        - $ref: "#/components/parameters/page_size"
      security:
        - Authorize: []
    post:
      operationId: postRatingsAnalyses
      summary: Submit a new city to analyze
      description: Submit a new city to analyze
      tags:
        - rating
      requestBody:
        description: Create a new analysis performed by the brokenspoke-analyzer
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/analysis_post"
      responses:
        201:
          $ref: "#/components/responses/analysis"
        400:
          $ref: "#/components/responses/bad_request"
      security:
        - Authorize: []
  /ratings/analyses/{analysis_id}:
    get:
      operationId: getAnalysis
      summary: Get the summary of a specific analysis
      description: Get the summary of a specific analysis .
      tags:
        - rating
      parameters:
        - $ref: "#/components/parameters/analysis_id"
      responses:
        200:
          $ref: "#/components/responses/analysis"
        400:
          $ref: "#/components/responses/bad_request"
        403:
          $ref: "#/components/responses/forbidden"
        404:
          $ref: "#/components/responses/not_found"
      security:
        - Authorize: []
    patch:
      operationId: patchAnalysis
      summary: Update an analysis
      description: Update an analysis
      tags:
        - rating
      requestBody:
        description: Update a new analysis performed by the brokenspoke-analyzer
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/analysis_patch"
      responses:
        200:
          $ref: "#/components/responses/analysis"
        400:
          $ref: "#/components/responses/bad_request"
        403:
          $ref: "#/components/responses/forbidden"
        404:
          $ref: "#/components/responses/not_found"
      security:
        - Authorize: []
    parameters:
      - $ref: "#/components/parameters/analysis_id"
  /ratings/{rating_id}:
    get:
      operationId: getRating
      summary: Get a specific city rating summary
      description: Get a specific city rating summary.
      tags:
        - rating
      responses:
        200:
          $ref: "#/components/responses/rating"
        400:
          $ref: "#/components/responses/bad_request"
        404:
          $ref: "#/components/responses/not_found"
    parameters:
      - $ref: "#/components/parameters/rating_id"
      - $ref: "#/components/parameters/component"
  /ratings/{rating_id}/city:
    get:
      operationId: getRatingCity
      summary: Get a specific city rating summary and its associated city details
      description: Get a specific city rating summary and its associated city details.
      tags:
        - rating
      responses:
        200:
          $ref: "#/components/responses/rating_summary_with_city"
        400:
          $ref: "#/components/responses/bad_request"
        404:
          $ref: "#/components/responses/not_found"
    parameters:
      - $ref: "#/components/parameters/rating_id"
  /cities:
    get:
      operationId: getCities
      summary: Get city details
      description: Get the details of all cities where an BNA analysis was performed.
      tags:
        - city
      responses:
        200:
          $ref: "#/components/responses/cities"
      parameters:
        - $ref: "#/components/parameters/page"
        - $ref: "#/components/parameters/page_size"
    post:
      operationId: postCity
      summary: Create a new city
      description: Create a new city.
      tags:
        - city
      requestBody:
        description: Create a new city.
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/city_post"
      responses:
        201:
          $ref: "#/components/responses/city"
        400:
          $ref: "#/components/responses/bad_request"
      parameters:
        - $ref: "#/components/parameters/page"
        - $ref: "#/components/parameters/page_size"
      security:
        - Authorize: [write]
  /cities/submissions:
    get:
      operationId: getCitySubmissions
      summary: Get the cities that were submitted for analysis
      description: Get the cities that were submitted for analysis.
      tags:
        - city
      responses:
        200:
          $ref: "#/components/responses/submissions"
      parameters:
        - $ref: "#/components/parameters/page"
        - $ref: "#/components/parameters/page_size"
    post:
      operationId: postCitySubmission
      summary: Submit a new city for analysis
      description: Submit a new city for analysis.
      tags:
        - city
      requestBody:
        description: Create a new analysis to be performed by the brokenspoke-analyzer
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/submission_post"
      responses:
        201:
          $ref: "#/components/responses/submission"
        400:
          $ref: "#/components/responses/bad_request"
  /cities/submissions/{submission_id}:
    get:
      operationId: getCitySubmission
      summary: Get the details of a specific sumission
      description: Get the details of a specific sumission.
      tags:
        - city
      responses:
        200:
          $ref: "#/components/responses/submission"
        400:
          $ref: "#/components/responses/bad_request"
        404:
          $ref: "#/components/responses/not_found"
    patch:
      operationId: patchCitySubmissions
      summary: Update the details of a specific sumission
      description: Update the details of a specific sumission.
      tags:
        - city
      requestBody:
        description: Update the details of a specific sumission.
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/submission_patch"
      responses:
        200:
          $ref: "#/components/responses/submission"
        400:
          $ref: "#/components/responses/bad_request"
        403:
          $ref: "#/components/responses/forbidden"
        404:
          $ref: "#/components/responses/not_found"
      security:
        - Authorize: []
    parameters:
      - $ref: "#/components/parameters/submission_id"
  /cities/{country}/{region}/{name}:
    get:
      operationId: getCity
      summary: Get the details of specific city
      description: >
        Get the details of a specific city where an BNA analysis was computed.

      tags:
        - city
      responses:
        200:
          $ref: "#/components/responses/city"
        400:
          $ref: "#/components/responses/bad_request"
        404:
          $ref: "#/components/responses/not_found"
    parameters:
      - $ref: "#/components/parameters/country"
      - $ref: "#/components/parameters/region"
      - $ref: "#/components/parameters/name"
  /cities/{country}/{region}/{name}/ratings:
    get:
      operationId: getCityRatings
      summary: >
        Get the details of a specific city with all the analysis that were performed
        against it

      description: >
        Get the details of a specific city with all the analysis that were performed
        against it.

      tags:
        - city
      responses:
        200:
          $ref: "#/components/responses/city_with_ratings"
        400:
          $ref: "#/components/responses/bad_request"
        404:
          $ref: "#/components/responses/not_found"
    parameters:
      - $ref: "#/components/parameters/country"
      - $ref: "#/components/parameters/region"
      - $ref: "#/components/parameters/name"
  /cities/{country}/{region}/{name}/census:
    get:
      operationId: getCityCensus
      summary: >
        Get the details of a specific city with its associated census information.

      description: >
        Get the details of a specific city with its associated census information.

      tags:
        - city
      responses:
        200:
          $ref: "#/components/responses/city_with_census"
        400:
          $ref: "#/components/responses/bad_request"
        404:
          $ref: "#/components/responses/not_found"
    post:
      operationId: patchCityCensus
      summary: Create census information for a specific city.
      description: Create census information for a specific city.
      tags:
        - city
      requestBody:
        description: Create the census information for a specific city.
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/census_post"
      responses:
        201:
          $ref: "#/components/responses/city_with_census"
        400:
          $ref: "#/components/responses/bad_request"
        404:
          $ref: "#/components/responses/not_found"
      security:
        - Authorize: []
    parameters:
      - $ref: "#/components/parameters/country"
      - $ref: "#/components/parameters/region"
      - $ref: "#/components/parameters/name"
  /ratings/enqueue:
    post:
      operationId: postRatingEnqueue
      summary: Enqueue a city to process
      description: Enqueue a city to process.
      tags:
        - rating
      requestBody:
        description: Create a new city to enqueue.
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/enqueue_post"
      responses:
        201:
          $ref: "#/components/responses/enqueue"
        400:
          $ref: "#/components/responses/bad_request"
        403:
          $ref: "#/components/responses/forbidden"
      security:
        - Authorize: []
  /price/fargate:
    get:
      operationId: getPricesFargate
      summary: "Get all the AWS Fargate prices used to compute analysis costs."
      description: "Get all the AWS Fargate prices used to compute analysis costs."
      tags:
        - price
      responses:
        200:
          $ref: "#/components/responses/fargate_prices"
  /price/fargate/{fargate_price_id}:
    get:
      operationId: getPriceFargate
      summary: "Get a AWS Fargate price used to compute the cost of an analysis."
      description: "Get a AWS Fargate price used to compute the cost of analysis cost."
      tags:
        - price
      parameters:
        - $ref: "#/components/parameters/fargate_price_id"
      responses:
        200:
          $ref: "#/components/responses/fargate_price"
        404:
          $ref: "#/components/responses/not_found"
components:
  schemas:
    analysis:
      type: object
      properties:
        cost:
          type: string
          format: decimal
          description: "Cost of an analysis in USD"
          example: "6.8941"
          nullable: true
        end_time:
          type: string
          format: date-time
          description: "Date and time"
          nullable: true
        fargate_price_id:
          type: integer
          description: "Fargate price identifier"
          example: 1
          nullable: true
        fargate_task_arn:
          type: string
          description: "The ARN of the Fargate task that performed the analysis"
          example: >
            arn:aws:ecs:us-west-2:123456789012:task/bna/29f979fc9fca402d94b014aa23d2f6e0
          nullable: true
        results_posted:
          type: boolean
          nullable: true
        s3_bucket:
          type: string
          description: "the path of the S3 bucket where the results were stored"
          example: "united states/new mexico/santa rosa/24.05.4"
          nullable: true
        sqs_message:
          type: string
          description: "Copy of the JSON message that was sent for processing"
          example: >-
            {"country":"United States","city":"santa rosa","region":"new mexico",
            "fips_code":"3570670"}
          nullable: true
        start_time:
          type: string
          format: date-time
          description: "Date and time"
          nullable: true
        state_machine_id:
          $ref: "#/components/schemas/state_machine_id"
        status:
          $ref: "#/components/schemas/analysis_status"
        step:
          $ref: "#/components/schemas/step"
        torn_down:
          type: boolean
          description: >
            Flag indicating wether the resources were torn down or not at the end of the
            analysis
          nullable: true
      required:
        - state_machine_id
    analysis_patch:
      type: object
      properties:
        cost:
          type: number
          format: double
          description: "Cost of an analysis in USD"
          example: 6.8941
          nullable: true
        end_time:
          type: string
          format: date-time
          description: "Date and time"
          nullable: true
        fargate_task_arn:
          type: string
          description: "The ARN of the Fargate task that performed the analysis"
          example: >
            arn:aws:ecs:us-west-2:123456789012:task/bna/29f979fc9fca402d94b014aa23d2f6e0
          nullable: true
        results_posted:
          type: boolean
          nullable: true
        s3_bucket:
          type: string
          description: "the path of the S3 bucket where the results were stored"
          example: "united states/new mexico/santa rosa/24.05.4"
          nullable: true
        sqs_message:
          type: string
          description: "Copy of the JSON message that was sent for processing"
          example: >-
            {"country":"United States","city":"santa rosa","region":"new mexico",
            "fips_code":"3570670"}
          nullable: true
        start_time:
          type: string
          format: date-time
          description: "Date and time"
          nullable: true
        status:
          $ref: "#/components/schemas/analysis_status"
        step:
          $ref: "#/components/schemas/step"
        torn_down:
          type: boolean
          description: >
            Flag indicating wether the resources were torn down or not at the end of the
            analysis
          nullable: true
    analysis_post:
      type: object
      properties:
        cost:
          type: number
          format: double
          description: "Cost of an analysis in USD"
          example: 6.8941
          nullable: true
        end_time:
          type: string
          format: date-time
          description: "Date and time"
          nullable: true
        fargate_task_arn:
          type: string
          description: "The ARN of the Fargate task that performed the analysis"
          example: >
            arn:aws:ecs:us-west-2:123456789012:task/bna/29f979fc9fca402d94b014aa23d2f6e0
          nullable: true
        result_posted:
          type: boolean
          nullable: true
        s3_bucket:
          type: string
          description: "the path of the S3 bucket where the results were stored"
          example: "united states/new mexico/santa rosa/24.05.4"
          nullable: true
        sqs_message:
          type: string
          description: "Copy of the JSON message that was sent for processing"
          example: >-
            {"country":"United States","city":"santa rosa","region":"new mexico",
            "fips_code":"3570670"}
          nullable: true
        start_time:
          type: string
          format: date-time
          description: "Date and time"
          nullable: true
        step:
          $ref: "#/components/schemas/step"
        torn_down:
          type: boolean
          description: >
            Flag indicating wether the resources were torn down or not at the end of the
            analysis
          nullable: true
        state_machine_id:
          $ref: "#/components/schemas/state_machine_id"
        fargate_price_id:
          type: number
          description: >
            Identifier of the Fargate Price rate used to compute the cost of the pipeline
            run.
        status:
          $ref: "#/components/schemas/analysis_status"
    analysis_status:
      type: string
      enum:
        - Completed
        - Pending
        - Processing
      description: "BNA Pipeline status"
      example: "Pending"
    api_gateway_id:
      type: string
      description: "API Gateway ID associated with the request "
      example: "blfwkg8nvHcEJnQ="
    bna:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: "Analysis identifier"
          example: "1a759b85-cd87-4bb1-9efa-5789e38e9982"
          nullable: false
        city_id:
          type: string
          format: uuid
          description: "City identifier"
          example: "6d1927b4-3474-4ce0-9b2e-2a1f5a7d91bd"
        community_centers:
          type: number
          description: "BNA category subscore for access to community centers"
          example: 70.7
          nullable: true
        coreservices_score:
          type: number
          description: "BNA category score for access to core services"
          example: 78.15
          nullable: true
        dentists:
          type: number
          description: "BNA category subscore for access to dentists"
          example: 68.69
          nullable: true
        doctors:
          type: number
          description: "BNA category subscore for access to doctors"
          example: 73.51
          nullable: true
        employment:
          type: number
          description: "BNA category subscore for access to job location areas"
          example: 0.0
          nullable: true
        grocery:
          type: number
          description: "BNA category subscore for access to grocery stores"
          example: 83.02
          nullable: true
        high_stress_miles:
          type: number
          description: "Total miles of high-stress streets in the measured area"
          example: 437.8
          nullable: true
        higher_education:
          type: number
          description: "BNA category subscore for access to universities and colleges"
          example: 84.76
          nullable: true
        hospitals:
          type: number
          description: "BNA category subscore for access to hospitals"
          example: 82.43
          nullable: true
        k12_education:
          type: number
          description: "BNA category subscore for access to k12 schools"
          example: 6.63
          nullable: true
        low_stress_miles:
          type: number
          description: "Total miles of low-stress streets and paths in the measured area"
          example: 1862.2
          nullable: true
        opportunity_score:
          type: number
          description: BNA category score for access to education and jobs""
          example: 79.91
          nullable: true
        parks:
          type: number
          description: "BNA category subscore for access to parks"
          example: 78.49
          nullable: true
        people:
          type: number
          description: "BNA category score for access to residential areas"
          example: 75.81
          nullable: true
        pharmacies:
          type: number
          description: "BNA category subscore for access to pharmacies"
          example: 76.62
          nullable: true
        recreation_score:
          type: number
          description: "BNA category score for access to recreational facilities"
          example: 82.13
          nullable: true
        recreation_trails:
          type: number
          description: "BNA category subscore for access to bikeable trails"
          example: 94.45
          nullable: true
        retail:
          type: number
          description: "BNA category score for access to major retail centers"
          example: 73.71
          nullable: true
        score:
          type: number
          description: "BNA total score"
          example: 77.0
        social_services:
          type: number
          description: "BNA category subscore for access to social services"
          example: 77.82
          nullable: true
        technical_vocational_college:
          type: number
          description: "BNA category subscore for access to technical and vocational colleges"
          example: 81.67
          nullable: true
        transit:
          type: number
          description: "BNA category score for access to major transit stops"
          example: 71.59
          nullable: true
        version:
          type: string
          description: >
            Analysis version. The format follows the [calver](https://calver.org)
            specification with the YY.0M[.Minor] scheme.

          example: "23.02"
      required:
        - id
        - city_id
        - score
        - version
    bna_post:
      type: object
      properties:
        core_services:
          $ref: "#/components/schemas/core_services"
        infrastructure:
          $ref: "#/components/schemas/infrastructure"
        opportunity:
          $ref: "#/components/schemas/opportunity"
        people:
          $ref: "#/components/schemas/people"
        recreation:
          $ref: "#/components/schemas/recreation"
        retail:
          $ref: "#/components/schemas/retail"
        summary:
          $ref: "#/components/schemas/bna_summary"
        transit:
          $ref: "#/components/schemas/transit"
      required:
        - core_services
        - infrastructure
        - opportunity
        - people
        - recreation
        - retail
        - summary
        - transit
    bna_summary:
      type: object
      properties:
        rating_id:
          type: string
          format: uuid
          description: "Analysis identifier"
          example: "1a759b85-cd87-4bb1-9efa-5789e38e9982"
        city_id:
          type: string
          format: uuid
          description: "City identifier"
          example: "6d1927b4-3474-4ce0-9b2e-2a1f5a7d91bd"
        created_at:
          type: string
          format: date-time
          description: "Date and time"
        score:
          type: number
          description: "BNA score"
          example: 77.0
        version:
          type: string
          description: >
            Analysis version. The format follows the [calver](https://calver.org)
            specification with the YY.0M[.Minor] scheme.

          example: "23.02"
      required:
        - city_id
        - rating_id
        - score
        - version
    bna_summary_with_city:
      type: array
      items:
        allOf:
          - $ref: "#/components/schemas/bna_summary"
          - $ref: "#/components/schemas/city"
    census:
      type: object
      description: "Census information"
      properties:
        census_id:
          type: integer
          example: 788
        city_id:
          type: string
          format: uuid
          description: "City identifier"
          example: "6d1927b4-3474-4ce0-9b2e-2a1f5a7d91bd"
        created_at:
          type: string
          format: date-time
          description: "Date and time"
        fips_code:
          type: string
          description: >
            Numerical city identifier given by the U.S. census, or 0 for non-US cities
          example: "4805000"
        pop_size:
          type: integer
          description: >
            City population size category (small (0), medium (1), large (2))

          enum:
            - 0
            - 1
            - 2
          example: 2
        population:
          type: integer
          description: "City population"
          example: 907779
    census_post:
      type: object
      properties:
        fips_code:
          type: string
          description: >
            Numerical city identifier given by the U.S. census, or 0 for non-US cities
          example: "4805000"
        pop_size:
          type: integer
          description: >
            City population size category (small (0), medium (1), large (2))

          enum:
            - 0
            - 1
            - 2
          example: 2
        population:
          type: integer
          description: "City population"
          example: 907779
    city:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: "City identifier"
          example: "6d1927b4-3474-4ce0-9b2e-2a1f5a7d91bd"
          nullable: false
        country:
          $ref: "#/components/schemas/country"
        created_at:
          type: string
          format: date-time
          description: "Date and time"
        latitude:
          type: number
          description: >
            Geographic coordinate that specifies the north-south position of a point on the
            surface of the Earth.
          example: 51.2194
        longitude:
          type: number
          description: >
            Geographic coordinate that specifies the east–west position of a point on the
            surface of the Earth.

          example: 4.4025
        name:
          type: string
          description: "City name"
          example: "Antwerp"
        region:
          type: string
          description: >
            Region name. A region can be a state, a province, a community, or something
            similar depending on the country. If a country does not have this concept, then
            the country name is used.

          example: "Belgium"
        speed_limit:
          type: number
          description: "Speed limit in kilometer per hour (km/h)."
          example: 50
        state:
          type: string
          description: "State name"
          example: "Antwerp"
        state_abbrev:
          type: string
          description: "A short version of the state name, usually 2 or 3 character long."
          example: "VAN"
        updated_at:
          type: string
          format: date-time
          description: "Date and time"
      required:
        - country
        - created_at
        - id
        - name
        - state
    city_post:
      type: object
      properties:
        country:
          $ref: "#/components/schemas/country"
        latitude:
          type: number
          description: >
            Geographic coordinate that specifies the north-south position of a point on the
            surface of the Earth.
          example: 51.2194
          nullable: true
        longitude:
          type: number
          description: >
            Geographic coordinate that specifies the east–west position of a point on the
            surface of the Earth.

          example: 4.4025
          nullable: true
        name:
          type: string
          description: "City name"
          example: "Antwerp"
        state:
          type: string
          description: "State name"
          example: "Antwerp"
        state_abbrev:
          type: string
          description: "A short version of the state name, usually 2 or 3 character long."
          example: "VAN"
        speed_limit:
          type: number
          description: "Speed limit in kilometer per hour (km/h)."
          example: 50
          nullable: true
      required:
        - country
        - name
    core_services:
      type: object
      properties:
        dentists:
          type: number
          description: "BNA category subscore for access to dentists"
          example: 68.69
        doctors:
          type: number
          description: "BNA category subscore for access to doctors"
          example: 73.51
        grocery:
          type: number
          description: "BNA category subscore for access to grocery stores"
          example: 83.02
        hospitals:
          type: number
          description: "BNA category subscore for access to hospitals"
          example: 82.43
        pharmacies:
          type: number
          description: "BNA category subscore for access to pharmacies"
          example: 76.62
        score:
          type: number
          description: "BNA total score"
          example: 77.0
        social_services:
          type: number
          description: "BNA category subscore for access to social services"
          example: 77.82
    country:
      type: string
      enum:
        - Australia
        - Belgium
        - Brazil
        - Canada
        - Chile
        - Colombia
        - Croatia
        - Cuba
        - England
        - France
        - Germany
        - Greece
        - Guatemala
        - Iran
        - Iraq
        - Ireland
        - Italy
        - Mexico
        - Netherlands
        - New Zealand
        - Northern Ireland
        - Portugal
        - Scotland
        - Spain
        - United States
        - Vietnam
        - Wales
    enqueue:
      type: object
      properties:
        country:
          $ref: "#/components/schemas/country"
        city:
          type: string
          description: "City name"
          example: "Antwerp"
        region:
          type: string
          description: >
            Region name. A region can be a state, a province, a community, or something
            similar depending on the country. If a country does not have this concept, then
            the country name is used.

          example: "Belgium"
        fips_code:
          type: string
          description: >
            Numerical city identifier given by the U.S. census, or 0 for non-US cities
          example: "4805000"
    enqueue_post:
      type: object
      properties:
        country:
          $ref: "#/components/schemas/country"
        city:
          type: string
          description: "City name"
          example: "Antwerp"
        region:
          type: string
          description: >
            Region name. A region can be a state, a province, a community, or something
            similar depending on the country. If a country does not have this concept, then
            the country name is used.

          example: "Belgium"
        fips_code:
          type: string
          description: >
            Numerical city identifier given by the U.S. census, or 0 for non-US cities
          example: "4805000"
    error:
      type: object
      description: >
        API Error object as described in <https://jsonapi.org/format/#error-objects>

      properties:
        id:
          $ref: "#/components/schemas/api_gateway_id"
        details:
          type: string
          description: "detailed error message"
          example: "the entry was not found"
        status:
          type: integer
          description: "HTTP status associated with the error"
          minimum: 400
          example: 404
        title:
          type: string
          description: "Error title"
          example: "Item Not Found"
        source:
          $ref: "#/components/schemas/source"
    errors:
      type: array
      description: "A collection of errors"
      items:
        $ref: "#/components/schemas/error"
    header:
      type: string
      description: "The name of a single request header which caused the error"
      example: "Authorization"
    infrastructure:
      type: object
      properties:
        low_stress_miles:
          type: number
          description: "Total miles of low-stress streets and paths in the measured area"
          example: 1862.2
        high_stress_miles:
          type: number
          description: "Total miles of high-stress streets in the measured area"
          example: 437.8
    opportunity:
      type: object
      properties:
        employment:
          type: number
          description: "BNA category subscore for access to job location areas"
          example: 0.0
        higher_education:
          type: number
          description: "BNA category subscore for access to universities and colleges"
          example: 84.76
        k12_education:
          type: number
          description: "BNA category subscore for access to k12 schools"
          example: 6.63
        score:
          type: number
          description: BNA category score for access to education and jobs""
          example: 79.91
        technical_vocational_college:
          type: number
          description: "BNA category subscore for access to technical and vocational colleges"
          example: 81.67
    parameter:
      type: string
      description: "The URI query parameter caused the error"
      example: "/bnas/analysis/e6aade5a-b343-120b-dbaa-bd916cd99221?"
    pointer:
      type: string
      description: >
        A JSON Pointer [RFC6901](https://tools.ietf.org/html/rfc6901) to the value in
        the request document that caused the error [e.g. "/data" for a primary data
        object, or "/data/attributes/title" for a specific attribute].

      example: "/data"
    recreation:
      type: object
      properties:
        community_centers:
          type: number
          description: "BNA category subscore for access to community centers"
          example: 70.7
        parks:
          type: number
          description: "BNA category subscore for access to parks"
          example: 78.49
        recreation_trails:
          type: number
          description: "BNA category subscore for access to bikeable trails"
          example: 94.45
        score:
          type: number
          description: "BNA total score"
          example: 77.0
    source:
      type: object
      description: "An object containing references to the primary source of the error."
      oneOf:
        - $ref: "#/components/schemas/parameter"
        - $ref: "#/components/schemas/pointer"
        - $ref: "#/components/schemas/header"
      example:
        source: Parameter "/bnas/analysis/e6aade5a-b343-120b-dbaa-bd916cd99221?"
    state_machine_id:
      type: string
      format: uuid
      description: "ID of the AWS state machine that was used to run the pipeline"
      example: "38f4f54e-98d6-4048-8c0f-99cde05a7e76"
    step:
      type: string
      enum:
        - SqsMessage
        - Setup
        - Analysis
        - Cleanup
      description: "Indicate the last step of the pipeline that completed successfully"
      example: "Cleanup"
    submission:
      type: object
      properties:
        city:
          type: string
          description: "City name"
          example: "Antwerp"
        consent:
          type: boolean
          nullable: true
          description: "Consent status"
          example: true
        country:
          $ref: "#/components/schemas/country"
        created_at:
          type: string
          format: date-time
          description: "Date and time"
        email:
          type: string
          description: Email address
          example: "jane.doe@orgllc.com"
        fips_code:
          type: string
          description: >
            Numerical city identifier given by the U.S. census, or 0 for non-US cities
          example: "4805000"
        first_name:
          type: string
          description: "First name"
          example: "Jane"
        id:
          type: integer
          description: "Submission identifier"
          example: 1
        last_name:
          type: string
          description: "Last name"
          example: "Doe"
        organization:
          type: string
          description: "Name of the organization"
          example: "Organization LLC"
        region:
          type: string
          description: >
            Region name. A region can be a state, a province, a community, or something
            similar depending on the country. If a country does not have this concept, then
            the country name is used.

          example: "Belgium"
        submission_status:
          type: string
          description: "The current status of the submission"
          example: "Pending"
        occupation:
          type: string
          description: "Job title or position"
          example: "CTO"
    submission_patch:
      type: object
      properties:
        first_name:
          type: string
          description: "First name"
          example: "Jane"
          nullable: true
        last_name:
          type: string
          description: "Last name"
          example: "Doe"
          nullable: true
        occupation:
          type: string
          description: "Job title or position"
          example: "CTO"
          nullable: true
        organization:
          type: string
          description: "Name of the organization"
          example: "Organization LLC"
          nullable: true
        email:
          type: string
          description: Email address
          example: "jane.doe@orgllc.com"
          nullable: true
        country:
          $ref: "#/components/schemas/country"
        city:
          type: string
          description: "City name"
          example: "Antwerp"
          nullable: true
        region:
          type: string
          description: >
            Region name. A region can be a state, a province, a community, or something
            similar depending on the country. If a country does not have this concept, then
            the country name is used.

          example: "Belgium"
          nullable: true
        fips_code:
          type: string
          description: >
            Numerical city identifier given by the U.S. census, or 0 for non-US cities
          example: "4805000"
          nullable: true
        consent:
          type: boolean
          description: "Consent status"
          example: true
          nullable: true
        submission_status:
          type: string
          description: "The current status of the submission"
          example: "Pending"
          nullable: true
    submission_post:
      type: object
      properties:
        first_name:
          type: string
          description: "First name"
          example: "Jane"
        last_name:
          type: string
          description: "Last name"
          example: "Doe"
        occupation:
          type: string
          description: "Job title or position"
          example: "CTO"
          nullable: true
        organization:
          type: string
          description: "Name of the organization"
          example: "Organization LLC"
          nullable: true
        email:
          type: string
          description: Email address
          example: "jane.doe@orgllc.com"
        country:
          $ref: "#/components/schemas/country"
        city:
          type: string
          description: "City name"
          example: "Antwerp"
        region:
          type: string
          description: >
            Region name. A region can be a state, a province, a community, or something
            similar depending on the country. If a country does not have this concept, then
            the country name is used.

          example: "Belgium"
          nullable: true
        fips_code:
          type: string
          description: >
            Numerical city identifier given by the U.S. census, or 0 for non-US cities
          example: "4805000"
        consent:
          type: boolean
          description: "Consent status"
          example: true
        submission_status:
          type: string
          description: "The current status of the submission"
          example: "Pending"
      required:
        - city
        - consent
        - country
        - email
        - fips_code
        - first_name
        - last_name
    submissions:
      type: array
      description: "A collection of submissions"
      items:
        $ref: "#/components/schemas/submission"
    people:
      type: object
      properties:
        score:
          type: number
    retail:
      type: object
      properties:
        score:
          type: number
    transit:
      type: object
      properties:
        score:
          type: number
    fargate_price:
      type: object
      properties:
        fargate_price_id:
          type: number
          description: >
            Identifier of the Fargate Price rate used to compute the cost of the pipeline
            run.
          example: 1
        per_second:
          type: string
          format: decimal
          description: Cost to run Fargate for 1 second
          example: "0.0023"
        created_at:
          type: string
          format: date-time
          description: "Date and time"

  parameters:
    rating_id:
      name: "rating_id"
      in: "path"
      description: "Analysis identifier"
      required: true
      schema:
        type: string
        format: uuid
        description: "Analysis identifier"
        example: "1a759b85-cd87-4bb1-9efa-5789e38e9982"
    country:
      name: "country"
      in: "path"
      description: "Country name"
      required: true
      schema:
        $ref: "#/components/schemas/country"
    name:
      name: "name"
      in: "path"
      description: "City name"
      required: true
      schema:
        type: string
        description: "City name"
        example: "Antwerp"
    region:
      name: "region"
      in: "path"
      description: >
        Region name. A region can be a state, a province, a community, or something
        similar depending on the country. If a country does not have this concept, then
        the country name is used.

      required: true
      schema:
        type: string
        description: >
          Region name. A region can be a state, a province, a community, or something
          similar depending on the country. If a country does not have this concept, then
          the country name is used.

        example: "Belgium"
    analysis_id:
      name: analysis_id
      in: path
      required: true
      description: State Machine Identifier
      schema:
        $ref: "#/components/schemas/state_machine_id"
    submission_id:
      name: "submission_id"
      in: "path"
      description: "Submission identifier"
      required: true
      schema:
        type: integer
        description: "Submission identifier"
        example: 1
    component:
      name: component
      in: query
      required: false
      description: >
        Select a component to retrieve alongside the BNA summary. If none is specified,
        all the components are returned.
      schema:
        type: string
        enum:
          - All
          - CoreServices
          - Infratructure
          - Opportunity
          - People
          - Recreation
          - Retail
          - Summary
          - Transit
        example: All
    page:
      name: page
      in: query
      required: false
      description: "Page index (starting at 0)"
      schema:
        type: integer
        default: 1
        example: 1
        minimum: 1
        maximum: 65535
    page_size:
      name: page_size
      in: query
      required: false
      description: "The number of items to be returned per page (1..50)"
      schema:
        type: integer
        default: 25
        example: 25
        minimum: 1
        maximum: 65535
    fargate_price_id:
      name: fargate_price_id
      in: path
      required: true
      description: "Identifier of a Fargate price"
      schema:
        type: integer
  responses:
    analyses:
      description: "A collection of BNA analysis"
      content:
        application/json:
          schema:
            type: array
            items:
              $ref: "#/components/schemas/analysis"
    analysis:
      description: "An analysis"
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/analysis"
    bad_request:
      description: >
        Your request was formatted incorrectly or missing required parameters.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/errors"

    rating:
      description: "A city rating"
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/bna"
    rating_summaries:
      description: "A collection of city rating summaries"
      content:
        application/json:
          schema:
            type: array
            items:
              $ref: "#/components/schemas/bna_summary"
    rating_summary:
      description: "A city rating Summary object"
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/bna_summary"
    rating_summary_with_city:
      description: "A city rating summary object and its associated city"
      content:
        application/json:
          schema:
            type: array
            items:
              anyOf:
                - $ref: "#/components/schemas/bna_summary_with_city"
                - $ref: "#/components/schemas/city"
    ratings:
      description: "A collection of city ratings"
      content:
        application/json:
          schema:
            type: array
            items:
              $ref: "#/components/schemas/bna"
    cities:
      description: "Array of cities"
      content:
        application/json:
          schema:
            type: array
            items:
              $ref: "#/components/schemas/city"
    city:
      description: "A city"
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/city"
    city_with_ratings:
      description: "A city with its associated BNA analyses"
      content:
        application/json:
          schema:
            type: array
            items:
              anyOf:
                - $ref: "#/components/schemas/city"
                - $ref: "#/components/schemas/bna_summary"
    city_with_census:
      description: "A city with its census information"
      content:
        application/json:
          schema:
            type: array
            items:
              anyOf:
                - $ref: "#/components/schemas/city"
                - $ref: "#/components/schemas/census"
    enqueue:
      description: "An entry to enqueue a city to process "
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/enqueue"
    forbidden:
      description: >
        You weren't authorized to make your request; most likely this indicates an issue
        with your credentials or permissions.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/errors"

    not_found:
      description: >
        The particular resource you are requesting was not found. This occurs, for
        example, if you request a resource by an id that does not exist.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/errors"

    submission:
      description: "A submission"
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/submission"
    submissions:
      description: "A collection of submission"
      content:
        application/json:
          schema:
            type: array
            items:
              $ref: "#/components/schemas/submission"
    fargate_price:
      description: "Fargate price used to estimate the cost of an analysis."
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/fargate_price"
    fargate_prices:
      description: "A collection of Fargate prices"
      content:
        application/json:
          schema:
            type: array
            items:
              $ref: "#/components/schemas/fargate_price"

  securitySchemes:
    Authorize:
      description: |
        Bearer token using a JWT.

        Authenticate against AWS Cognito using the AWS CLI to obtain the token (replace the placeholders):

        `aws cognito-idp initiate-auth --auth-flow USER_PASSWORD_AUTH --client-id <client_id> --auth-parameters USERNAME=<username>,PASSWORD=<password>`
      type: http
      scheme: bearer
      bearerFormat: JWT