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: 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
    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
      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:
        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.
  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.
  TokenResponse:
    description: Resolves temporary token to ID of the 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
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:
  '/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: 638349
                status: open
                status_notes: null
                service_name: Sidewalk and Curb Issues
                service_code: 6
                description: null
                agency_responsible: null
                service_notice: null
                requested_datetime: '2010-04-19T14:37:38.000Z'
                updated_datetime: '2010-04-19T14:37:38.000Z'
                expected_datetime: '2010-04-19T14:37:38.000Z'
                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
          in: query
          required: false
          type: string
        - name: address_id
          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
          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: null
  '/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: 6
                description: null
                agency_responsible: null
                service_notice: null
                requested_datetime: '2010-04-14T14:37:38.000Z'
                updated_datetime: '2010-04-14T14:37:38.000Z'
                expected_datetime: '2010-04-15T14:37:38.000Z'
                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: 3
                  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: null
                    order: 1
                    description: What is the ticket/tag/DL number?
                    values:
                      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
          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