open311-georeporter.yaml

swagger: '2.0'

info:
  version: "2.0"
  title: Open311 GeoReport 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/

consumes:
        - application/x-www-form-urlencoded
produces:
        - application/json
        - text/xml
        
securityDefinitions:
  api_key:
    type: apiKey
    name: api_key
    in: query
	
definitions:
  Service:
    description: A single service (type) offered via Open311
    required:
      - service_code
      - service_name
      - type
    properties:
      service_code:
        type: string
        format: uid
        description: unique identifier for the service request type
      service_name:
        type: string
        description: human readable name of the service request type
      description:
        type: string
      metadata:
        type: boolean
        description: Are there additional form fields for this service type? If true use GET service definition for that one
      type:
        type: string
        description: Possible values realtime, batch, blackbox
        enum: 
          - realtime
          - batch
          - blackbox        
      keywords:
        type: array
        items:
          type: string
        description: list of keywords or tags seperated by comma
      group:
        type: string
        description: Category or group to cluster different request types e.g. “sanitation”
  
  ServiceDefinition:
    description: Attributes associated with a service code. These attributes can be unique to the city/jurisdiction.
    required:
      - service_code
      - attributes #todo How to make sure it's not empty?
    properties:
      service_code:
        type: string
        format: uid
        description: unique identifier for the service request type
      attributes:
        type: array
        items:
          $ref: '#/definitions/ServiceAttribute'
          
  ServiceAttribute:
    description: A single attribute extension for a service
    required:
      - variable
      - code
      - datatype
      - required
    properties:
      variable:
        type: boolean
        description: If only used to present information to the user within the description field or if that user input is needed
      code:
        type: string
        format: uid
        description: Unique identifier for the attribute #<?>why and limitations
      datatype:
        type: string
        enum:
          - string
          - number
          - datetime
          - text
          - singlevaluelist
          - multivaluelist
        description: Type of field used for user input. According widgets will be picked for user inputs
      required:
        type: boolean
        description: If attributes value required to submit service request 
      datatype_description:
        type: string
        description: Description of the datatype which helps the user provide their input
      order:
        type: integer
        format: uint
        description: Sort order that the attributes will be presented to the user. 1 is shown first in the list.
      description:
        type: string
        description: description of the attribute field with instructions for the user to find and identify the requested information
      values:
        type: array
        items:
          $ref: '#/definitions/AttributeValue'
          
  AttributeValue:
    description: Possible value for ServiceAttribute that defines lists
    required:
      - key
      - name
    properties:
      key:
        type: string
        format: uid
        description: Unique identifier associated with an option for singlevaluelist or multivaluelist (analogous to the value attribute in an html option tag).
      name:
        type: string
        description: Human readable title of an option for singlevaluelist or multivaluelist (analogous to the innerhtml text node of an html option tag).

  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: #todo Generalization and linking
      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:
      #<?> optional or required?
      type: string
      description: Internal address ID used by a jurisdictions master address repository or other addressing system.
    zipcode:
      #<?> Already mentioned in address descr?
      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: #Generalisation with
      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
      #<?> so we write we don't know how to submit
      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.
    
    
  RequestResponse:
    description: Details for tracking an created service request
    properties: #todo service_requests array?
      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.

  TokenResponse:
    description: Resolves temporary token to ID of the request
    properties: #todo service_requests array?
      service_request_id: #todo general request ID concept
        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

parameters:
  jurisdiction_id:
    name: jurisdiction_id
    in: query
    description: <?>
    required: true
    type: string
    format: uid
  response_format:
    name: response_format
    in: path
    required: true
    type: string
    format: uid
        
paths:
#todo extract service_code?
#todo extract an error model for responses?
  /requests.{response_format}:
    get:
      summary: requests
      description: Query the current status of multiple requests.
      parameters:
        -  $ref: '#/parameters/response_format'
        - $ref: '#/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
          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
          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
          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
          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
          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).
          schema:
            type: array
            items:
             $ref: '#/definitions/Request'
          examples:
            application/xml:
              request:
                service_request_id: 638344
                status: closed
                status_notes: Duplicate request.
                service_name: Sidewalk and Curb Issues
                service_code: 006
                description: 
                agency_responsible:
                service_notice:
                requested_datetime: 2010-04-14T06:37:38-08:00
                updated_datetime: 2010-04-14T06:37:38-08:00
                expected_datetime: 2010-04-15T06:37:38-08:00
                address: 8TH AVE and JUDAH ST
                address_id: 545483
                zipcode: 94122
                lat: 37.762221815
                long: -122.4651145
                media_url: http://city.gov.s3.amazonaws.com/requests/media/638344.jpg
            application/json:
              request:
                service_request_id: 638349
                status: open
                status_notes:
                service_name: Sidewalk and Curb Issues
                service_code: 006
                description: 
                agency_responsible:
                service_notice:
                requested_datetime: 2010-04-19T06:37:38-08:00
                updated_datetime: 2010-04-19T06:37:38-08:00
                expected_datetime: 2010-04-19T06:37:38-08:00
                address: 8TH AVE and JUDAH ST
                address_id: 545483
                zipcode: 94122
                lat: 37.762221815
                long: -122.4651145
                media_url: http://city.gov.s3.amazonaws.com/requests/media/638344.jpg
              
        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)
    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: '#/parameters/response_format'
        - $ref: '#/parameters/jurisdiction_id'
        - name: service_code
          in: query
          description: <?>
          required: true
          type: string
          format: uid
        - name: lat
          in: query
          description: WGS-84 latitude
          required: false
          type: number
          format: double
        - name: long
          in: query
          description: WGS-84 longitude
          required: false
          type: number
          format: double
        - name: address_string #todo any formal definition?
          in: query
          required: false
          type: string
        - name: address_id #todo any formal definition?
          in: query
          required: false
          type: string
          format: uid
        - name: attribute
          in: query
          description: array of key/value responses based on Service Definitions.
          required: false
          type: array
          items:
            type: string #todo $ref: '#/definitions/ServiceAttribute'
          collectionFormat: multi
      responses:
        200:
          description: success returns an tracking-id
          schema:
            type: array
            items:
              $ref: "#/definitions/RequestResponse"
          examples:
            application/xml:
              service_requests:
                service_request_id: 293944
                service_notice: The City will inspect and require the responsible party to correct within 24 hours and/or issue a Correction Notice or Notice of Violation of the Public Works Code
                account_id:
                
  
  /request/{service_request_id}.{response_format}:
    get:
      summary: current status
      description: Query the current status of an individual request
      parameters:
        -  $ref: '#/parameters/response_format'
        - $ref: '#/parameters/jurisdiction_id'
        - name: service_request_id
          in: path
          description: Is specified in the main URL path rather than an added query string parameter.
          required: true
          type: string
          format: uid
      responses:
        200:
          description: success returns request details
          schema:
              $ref: "#/definitions/Request"
          examples:
            application/xml:
              request:
                service_request_id: 638344
                status: closed
                status_notes: Duplicate request.
                service_name: Sidewalk and Curb Issues
                service_code: 006
                description: 
                agency_responsible:
                service_notice:
                requested_datetime: 2010-04-14T06:37:38-08:00
                updated_datetime: 2010-04-14T06:37:38-08:00
                expected_datetime: 2010-04-15T06:37:38-08:00
                address: 8TH AVE and JUDAH ST
                address_id: 545483
                zipcode: 94122
                lat: 37.762221815
                long: -122.4651145
                media_url: http://city.gov.s3.amazonaws.com/requests/media/638344.jpg
          

          
  /services.{response_format}:
    get:
      summary: service types
      description: List acceptable service request types and their associated service codes. These request types can be unique to the city/jurisdiction.
      parameters:
        - $ref: '#/parameters/jurisdiction_id'
        -  $ref: '#/parameters/response_format'
      responses:
        200:
          description: ok
          schema:
              type: array
              items:
                $ref: '#/definitions/Service'
          examples:
            application/xml:
              services:
                - service:
                    service_code: 001
                    service_name: Cans left out 24x7
                    description: Garbage or recycling cans that have been left out for more than 24 hours after collection. Violators will be cited.
                    metadata: true
                    type: realtime
                    keywords: lorem, ipsum, dolor
                    group: sanitation
                - service:
                    service_code: 002
                    service_name: Construction plate shifted
                    description: Metal construction plate covering the street or sidewalk has been moved.
                    metadata: true
                    type: realtime
                    keywords: lorem, ipsum, dolor
                    group: street
                - service:
                    service_code: 003
                    service_name: Curb or curb ramp defect
                    description: Sidewalk curb or ramp has problems such as cracking, missing pieces, holes, and/or chipped curb.
                    metadata: true
                    type: realtime
                    keywords: lorem, ipsum, dolor
                    group: street
                  
        400:
          description: The URL request is invalid or service is not running or reachable. Client should notify us after checking URL
        404:
          description: jurisdiction_id provided was not found (specify in error response).
          
  /services/{service_code}.{response_format}:
    get:
      summary: (extended) definition of a service type
      description: Define attributes associated with a service code. These attributes can be unique to the city/jurisdiction.
      parameters:
        - $ref: '#/parameters/jurisdiction_id'
        -  $ref: '#/parameters/response_format'
        - name: service_code
          in: path
          required: true
          type: string
          format: uid
      responses:
        200:
          description: returns ServiceDefinition for the Service
          schema:
            $ref: '#/definitions/ServiceDefinition'
          examples:
            application/xml:
              service_definition:
                service_code: DMV66
                attributes:
                  attribute:
                    variable: true
                    code: WHISHETN
                    datatype: singlevaluelist
                    required: true
                    datatype_description:
                    order: 1
                    description: What is the ticket/tag/DL number?
                    values:
                      - value:
                          key: 123
                          name: Ford
                      - value:
                          key: 124
                          name: Chrysler
                
        400:
          description: service_code or jurisdiction_id provided were not found (specify in erraddor response)
        404:
          description: service_code or jurisdiction_id provided were not found (specify in error response)

  /tokens/{token_id}.{response_format}:
    get:
      summary: Id of service_request via token
      description: Get the service_request_id from a temporary token. This is unnecessary if the response from creating a service request does not contain a token.
      parameters:
        - $ref: '#/parameters/jurisdiction_id'
        -  $ref: '#/parameters/response_format'
        - name: token_id #todo link with POST Service req
          in: path
          required: true
          type: string
          format: uid
      responses:
        200:
          description: returns tuple request ID, token
          schema:
            $ref: '#/definitions/TokenResponse'
          examples:
            application/xml:
              service_requests:
                request:
                  service_request_id: 638344
                  token: 12345