CivicPlus Requests.{response Format} API

openapi: 3.2.0
info:
  version: '2.0'
  title: Open311 GeoReport Requests.{response Format} API
  description: Open311 allows you to get/post civic information of cities via a unified interface. The GeoReport part allows you to submit and view issues at the public local space
  termsOfService: (depends on server instance for example NYC http://dev.cityofchicago.org/docs/api/tos)
  contact:
    name: Open311 community
    url: http://wiki.open311.org/GeoReport_v2/
    email: discuss@lists.open311.org
  license:
    name: CC BY 3.0
    url: http://creativecommons.org/licenses/by/3.0/
tags:
- name: Requests.{response Format}
paths:
  /requests.{response_format}:
    get:
      summary: requests
      description: Query the current status of multiple requests.
      parameters:
      - $ref: '#/components/parameters/response_format'
      - $ref: '#/components/parameters/jurisdiction_id'
      - name: service_request_id
        in: query
        description: To call multiple Service Requests at once, multiple service_request_id can be declared; comma delimited.This overrides all other arguments.
        required: false
        schema:
          type: string
          format: uid
      - name: service_code
        in: query
        description: Specify the service type by calling the unique ID of the service_code.
        required: false
        schema:
          type: string
      - name: start_date
        in: query
        description: Earliest datetime to include in search. When provided with end_date, allows one to search for requests which have a requested_datetime that matches a given range, but may not span more than 90 days.
        required: false
        schema:
          type: string
          format: date-time
      - name: end_date
        in: query
        description: Latest datetime to include in search. When provided with start_date, allows one to search for requests which have a requested_datetime that matches a given range, but may not span more than 90 days.
        required: false
        schema:
          type: string
          format: date-time
      - name: status
        in: query
        description: Allows one to search for requests which have a specific status. This defaults to all statuses; can be declared multiple times, comma delimited.
        required: false
        schema:
          type: string
          enum:
          - open
          - closed
      responses:
        200:
          description: List of matching requests (Default query limit is a span of 90 days or first 1000 requests returned, whichever is smallest).
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Request'
            text/xml:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Request'
        400:
          description: jurisdiction_id was not provided (specified in error response) or General Service error (Any failure during service query processing. Client will have to notify us)
        401:
          description: jurisdiction_id not found (specified in error response)
      tags:
      - Requests.{response Format}
      operationId: getRequests{responseFormat}
      x-operation-id-source: derived
    post:
      summary: Create service request
      description: Submit a new request for with specific details of a single service. Must provide a location via lat/long or address_string or address_id
      security:
      - api_key: []
      parameters:
      - $ref: '#/components/parameters/response_format'
      - $ref: '#/components/parameters/jurisdiction_id'
      - name: service_code
        in: query
        description: <?>
        required: true
        schema:
          type: string
          format: uid
      - name: lat
        in: query
        description: WGS-84 latitude
        required: false
        schema:
          type: number
          format: double
      - name: long
        in: query
        description: WGS-84 longitude
        required: false
        schema:
          type: number
          format: double
      - name: address_string
        in: query
        required: false
        schema:
          type: string
      - name: address_id
        in: query
        required: false
        schema:
          type: string
          format: uid
      - name: attribute
        in: query
        description: array of key/value responses based on Service Definitions.
        required: false
        style: form
        explode: true
        schema:
          type: array
          items:
            type: string
      responses:
        200:
          description: success returns an tracking-id
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/RequestResponse'
            text/xml:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/RequestResponse'
      tags:
      - Requests.{response Format}
      operationId: postRequests{responseFormat}
      x-operation-id-source: derived
components:
  schemas:
    RequestResponse:
      description: Details for tracking an created service request
      properties:
        service_request_id:
          type: string
          format: uid
          description: Unique ID of the service request created.
        token:
          type: string
          format: uid
          description: Use this to call GET service_request_id from a token.
        service_notice:
          type: string
          description: Information about the action expected to fulfill the request or otherwise address the information reported.
        account_id:
          type: string
          format: uid
          description: Unique ID for the user account of the person submitting the request.
    Request:
      description: Issues that have been reported as service requests. Location is submitted via lat/long or address or address_id
      required:
      - service_request_id
      - status
      - service_code
      - requested_datetime
      properties:
        service_request_id:
          type: string
          format: uid
          description: Unique ID of the service request created.
        status:
          type: string
          enum:
          - open
          - closed
          description: Current status of the service request.
        status_notes:
          type: string
          description: Explanation of why status was changed to current state or more details on current status than conveyed with status alone.
        service_name:
          type: string
          description: The human readable name of the service request type.
        service_code:
          type: string
          format: uid
          description: The unique identifier for the service request type
        description:
          type: string
          description: A full description of the request or report submitted.
        agency_responsible:
          type: string
          description: Agency responsible for fulfilling or otherwise addressing the service request.
        service_notice:
          type: string
          description: Information about the action expected to fulfill the request or otherwise address the information reported.
        requested_datetime:
          type: string
          format: date-time
          description: Date and time when the service request was made.
        updated_datetime:
          type: string
          format: date-time
          description: Date and time when the service request was last modified. For requests with status=closed, this will be the date the request was closed.
        expected_datetime:
          type: string
          format: date-time
          description: The date and time when the service request can be expected to be fulfilled. This may be based on a service-specific service level agreement.
        address:
          type: string
          description: Human readable address or description of location. This should be provided from most specific to most general geographic unit, eg address number or cross streets, street name, neighborhood/district, city/town/village, county, postal code.
        address_id:
          type: string
          description: Internal address ID used by a jurisdictions master address repository or other addressing system.
        zipcode:
          type: string
          description: postal code for the location of the service request. (Redundant and field might be removed as it should be part of adress string)
        lat:
          type: number
          format: double
          description: latitude using the (WGS84) projection.
        long:
          type: number
          format: double
          description: longitude using the (WGS84) projection.
        media_url:
          type: string
          format: uri
          description: URL to media associated with the request, eg an image. A convention for parsing media from this URL has yet to be established, so currently it will be done on a case by case basis much like Twitter.com does. For example, if a jurisdiction accepts photos submitted via Twitpic.com, then clients can parse the page at the Twitpic URL for the image given the conventions of Twitpic.com. This could also be a URL to a media RSS feed where the clients can parse for media in a more structured way.
  parameters:
    jurisdiction_id:
      name: jurisdiction_id
      in: query
      description: <?>
      required: true
      schema:
        type: string
        format: uid
    response_format:
      name: response_format
      in: path
      required: true
      schema:
        type: string
        format: uid
  securitySchemes:
    api_key:
      type: apiKey
      name: api_key
      in: query