Reporting an Issue

Reporting an Issue is a three step process. Step 1 requires querying for a report form by location. Step 2 is querying the fields for the request type. Step 3 is to create an issue.

• Report form
• Details about a Request Type
• Question Types
• Select Values
• Request Type Answer Privacy
• Request Type & Questions for authenticated users
• Create an issue

Report form

GET https://seeclickfix.com/api/v2/issues/new?:point

Required Parameters

• :point - See how to specify a geography for syntax help.

Examples

$ curl -i "https://seeclickfix.com/api/v2/issues/new?lat=41.308274&lng=-72.9278835"

Return a list of request types for the given location. Each request type has an explicit organization which can be used to group the request types. A null organization represents a community request type that isn’t associated with any particular organization.

Response

Status: 200 OK

{
  "request_types": [
    {
      "organization": "City of SeeClickFix",
      "title": "Abandoned Auto",
      "url": "https://seeclickfix.com/api/v2/request_types/121"
    },
    {
      "organization": "City of SeeClickFix",
      "title": "Graffiti",
      "url": "https://seeclickfix.com/api/v2/request_types/657"
    },
    {
      "organization": "City of New Haven",
      "title": "Pothole",
      "url": "https://seeclickfix.com/api/v2/request_types/122"
    },
    {
      "organization": null,
      "title": "Other",
      "url": "https://seeclickfix.com/api/v2/request_types/other"
    }
  ]
}

Details about a Request Type

$ curl -i https://seeclickfix.com/api/v2/request_types/122

Response

Status: 200 OK

{
  "id": 122,
  "organization": "City of New Haven",
  "questions": [
    {
      "primary_key": "142",
      "question": "Depth of pothole?",
      "question_type": "select",
      "answer_kept_private": false,
      "response_required": true,
      "select_values": [
        {
          "key": "BUMPY",
          "name": "Bumpy Surface"
        },
        {
          "key": "SHALLOW",
          "name": "Shallow Hole"
        },
        {
          "key": "DEEP",
          "name": "Deep Hole"
        }
      ]
    },
    {
      "primary_key": "summary",
      "question": "Issue Title",
      "question_type": "text",
      "answer_kept_private": false,
      "response_required": true
    },
    {
      "primary_key": "description",
      "question": "Description",
      "question_type": "textarea",
      "answer_kept_private": false,
      "response_required": false
    },
    {
      "primary_key": "issue_image",
      "question": "Issue Image",
      "question_type": "file",
      "answer_kept_private": false,
      "response_required": false
    }
  ],
  "title": "Pothole"
}

Details of another Request Type

$ curl -i https://seeclickfix.com/api/v2/request_types/657

Response

Status: 200 OK

{
  "id": 657,
  "organization": "City of SeeClickFix",
  "questions": [
    {
      "primary_key": "400",
      "question": "Graffiti is on a surface of:",
      "question_type": "multivaluelist",
      "answer_kept_private": true,
      "response_required": true,
      "select_values": [
        {
          "key": "Brick",
          "name": "Brick"
        },
        {
          "key": "PaintedBrick",
          "name": "Painted Brick"
        },
        {
          "key": "Wood",
          "name": "Wood"
        },
        {
          "key": "PaintedWood",
          "name": "Painted Wood"
        },
        {
          "key": "Metal",
          "name": "Metal"
        },
        {
          "key": "Sandstone",
          "name": "Sandstone or rock"
        },
        {
          "key": "Pavers",
          "name": "Pavers"
        },
        {
          "key": "Concrete",
          "name": "Concrete"
        },
        {
          "key": "Tarmac",
          "name": "Tarmac"
        },
        {
          "key": "Tile",
          "name": "Tiles"
        },
        {
          "key": "Plastic",
          "name": "Plastic perspex"
        },
        {
          "key": "Glass",
          "name": "Glass"
        },
        {
          "key": "Other",
          "name": "Other"
        }
      ]
    },
    {
      "primary_key": "401",
      "question": "Material Used to apply graffiti",
      "question_type": "multivaluelist",
      "answer_kept_private": true,
      "response_required": true,
      "select_values": [
        {
          "key": "Paint",
          "name": "Paint"
        },
        {
          "key": "Pen",
          "name": "Pen"
        },
        {
          "key": "Texta",
          "name": "Texta"
        },
        {
          "key": "Whiteout",
          "name": "White out"
        },
        {
          "key": "Crayon",
          "name": "Crayon"
        },
        {
          "key": "Other",
          "name": "Other"
        }
      ]
    },
    {
      "primary_key": "offensive",
      "question": "Is the graffiti offensive?",
      "question_type": "boolean",
      "answer_kept_private": true,
      "response_required": true
    },
    {
      "primary_key": "summary",
      "question": "Issue Title",
      "question_type": "text",
      "answer_kept_private": false,
      "response_required": true
    },
    {
      "primary_key": "description",
      "question": "Description",
      "question_type": "textarea",
      "answer_kept_private": false,
      "response_required": false
    },
    {
      "primary_key": "issue_image",
      "question": "Issue Image",
      "question_type": "file",
      "answer_kept_private": false,
      "response_required": false
    }
  ],
  "title": "Graffiti"
}

We will always provide an “Other” request_type. In the event one is not supplied by the city we will provide one.

$ curl -i https://seeclickfix.com/api/v2/request_types/other

Response

Status: 200 OK

{
  "id": null,
  "organization": "Community",
  "questions": [
    {
      "primary_key": "summary",
      "question": "Issue Title",
      "question_type": "text",
      "answer_kept_private": false,
      "response_required": true
    },
    {
      "primary_key": "description",
      "question": "Description",
      "question_type": "textarea",
      "answer_kept_private": false,
      "response_required": false
    },
    {
      "primary_key": "issue_image",
      "question": "Issue Image",
      "question_type": "file",
      "answer_kept_private": false,
      "response_required": false
    }
  ],
  "title": "Post to Neighbors"
}

Question Types

• text - Short form text answer.
• textarea - Long form text answer.
• select - One value from supplied list.
• multivaluelist - One or more values from the supplied list. Submitted as an array.
• number - requires a numerical validation.
• datetime - ISO 8601 timestamp.
• boolean - Only true/false are acceptable answers
• note - No response expected, display as a note to the user.

Select Values

For select amd multivaluelist the use should we return a display value (name) and a key value (key).

Request Type Answer Privacy

The answer_kept_private field indicates whether or not the answer provided for a given request type question will be displayed publicly.

Request Type & Questions for authenticated users

Some request types & questions are only for specific authenticated users.

Create an issue

Issues can be created by any authenticated user.

POST https://seeclickfix.com/api/v2/issues

Required Parameters

• address - A written description of the location of the issue.
• lat - The latitude of the issue.
• lng - The longitude of the issue.
• answers - Answers to questions, if any questions are required.
• request_type_id - the id of your chosen Request Type

Optional Parameters

• anonymize_reporter - Wether or not to protect the identification of the reporter. Default is false. will evaluate to true.
• device_id - A unique identifier for the device creating the comment. This can help us debug problems.
• device_os - Device OS. This can help us debug problems.
• device_name - Model of device. This can help us debug problems.

Example request

  curl -i \
       --header "Content-Type: application/json" \
       --data '{
         "lat": 42.7265,
         "lng": -72.567,
         "address": "123 State St. New Haven, CT",
         "request_type_id": 122,
         "answers": {
           "142": "SHALLOW",
           "summary": "Big Pothole",
           "description": "Please fix it"
         }
       }' \
       https://seeclickfix.com/api/v2/issues

Response

Status: 201 Created
Location: http://seeclickfix.com/issues/1

{
  "id": 1,
  "status": "Open",
  "summary": "Pothole",
  "description": "Please fix my neighborhood.",
  "rating": "5",
  "lat": 42.30293,
  "lng": -72.234234234,
  "point": {
    "type": "Point",
    "coordinates": [
      -72.234234234,
      42.30293
    ]
  },
  "address": "123 State St. New Haven, CT",
  "created_at": "2011-04-22T13:33:48Z",
  "updated_at": "2011-04-22T13:33:48Z",
  "acknowledged_at": null,
  "closed_at": null,
  "reporter": {
    "avatar": {
      "full": "http://seeclickfix.com/files/user_images/0001/3476/32eebb4f8669b5beb441280bc16f26bf.jpeg",
      "square_100x100": "http://seeclickfix.com/files/user_images/0001/3476/32eebb4f8669b5beb441280bc16f26bf_square.jpeg"
    },
    "civic_points": 10,
    "id": 1,
    "name": "Jeffb",
    "role": "Verified Official",
    "witty_title": "Street Smart"
  },
  "shortened_url": "http://scf.cm/i/1",
  "url": "https://seeclickfix.com/api/v2/issues/1",
  "comments_url": "https://seeclickfix.com/api/v2/issues/1/comments",
  "flag_url": "https://seeclickfix.com/api/v2/issues/1/flag",
  "html_url": "http://seeclickfix.com/issues/1-pothole",
  "media": {
    "image_full": null,
    "image_square_100x100": null,
    "representative_image_url": "http://seeclickfix.com/files/default_image.png",
    "video_url": null
  }
}

Example request #2

  curl -i \
       --header "Content-Type: application/json" \
       --data '{
          "lat":42.7265,
          "lng":-72.567,
          "address": "123 State St. New Haven, CT",
          "request_type_id": 657,
          "answers": {
            "400": ["Brick", "PaintedBrick", "Wood"],
            "401": ["Other"],
            "offensive": false,
            "summary": "Graffiti on a brick wall"
          }
        }' \
       https://seeclickfix.com/api/v2/issues

Response

Status: 201 Created
Location: http://seeclickfix.com/issues/1

{
  "id": 1,
  "status": "Open",
  "summary": "Pothole",
  "description": "Please fix my neighborhood.",
  "rating": "5",
  "lat": 42.30293,
  "lng": -72.234234234,
  "point": {
    "type": "Point",
    "coordinates": [
      -72.234234234,
      42.30293
    ]
  },
  "address": "123 State St. New Haven, CT",
  "created_at": "2011-04-22T13:33:48Z",
  "updated_at": "2011-04-22T13:33:48Z",
  "acknowledged_at": null,
  "closed_at": null,
  "reporter": {
    "avatar": {
      "full": "http://seeclickfix.com/files/user_images/0001/3476/32eebb4f8669b5beb441280bc16f26bf.jpeg",
      "square_100x100": "http://seeclickfix.com/files/user_images/0001/3476/32eebb4f8669b5beb441280bc16f26bf_square.jpeg"
    },
    "civic_points": 10,
    "id": 1,
    "name": "Jeffb",
    "role": "Verified Official",
    "witty_title": "Street Smart"
  },
  "shortened_url": "http://scf.cm/i/1",
  "url": "https://seeclickfix.com/api/v2/issues/1",
  "comments_url": "https://seeclickfix.com/api/v2/issues/1/comments",
  "flag_url": "https://seeclickfix.com/api/v2/issues/1/flag",
  "html_url": "http://seeclickfix.com/issues/1-pothole",
  "media": {
    "image_full": null,
    "image_square_100x100": null,
    "representative_image_url": "http://seeclickfix.com/files/default_image.png",
    "video_url": null
  }
}

Example request #3, with image media

If you want to post an image when creating your issue, you must use multipart form data not json.

$ curl -i \
       --header "Content-Type: multipart/form-data" \
       --form "lat=42.7265" \
       --form "lng=-72.567" \
       --form "address=123 State St. New Haven, CT" \
       --form "request_type_id=other" \
       --form "answers[summary]=Found a pothole" \
       --form "answers[issue_image]=@photo.png" \
       https://seeclickfix.com/api/v2/issues

Response

Status: 201 Created
Location: http://seeclickfix.com/issues/1

{
  "id": 1,
  "status": "Open",
  "summary": "Pothole",
  "description": "Please fix my neighborhood.",
  "rating": "5",
  "lat": 42.30293,
  "lng": -72.234234234,
  "point": {
    "type": "Point",
    "coordinates": [
      -72.234234234,
      42.30293
    ]
  },
  "address": "123 State St. New Haven, CT",
  "created_at": "2011-04-22T13:33:48Z",
  "updated_at": "2011-04-22T13:33:48Z",
  "acknowledged_at": null,
  "closed_at": null,
  "reporter": {
    "avatar": {
      "full": "http://seeclickfix.com/files/user_images/0001/3476/32eebb4f8669b5beb441280bc16f26bf.jpeg",
      "square_100x100": "http://seeclickfix.com/files/user_images/0001/3476/32eebb4f8669b5beb441280bc16f26bf_square.jpeg"
    },
    "civic_points": 10,
    "id": 1,
    "name": "Jeffb",
    "role": "Verified Official",
    "witty_title": "Street Smart"
  },
  "shortened_url": "http://scf.cm/i/1",
  "url": "https://seeclickfix.com/api/v2/issues/1",
  "comments_url": "https://seeclickfix.com/api/v2/issues/1/comments",
  "flag_url": "https://seeclickfix.com/api/v2/issues/1/flag",
  "html_url": "http://seeclickfix.com/issues/1-pothole",
  "media": {
    "image_full": "http://seeclickfix.com/files/comment_images/0001/3476/32eebb4f8669b5beb441280bc16f26bf.jpeg",
    "image_square_100x100": "http://seeclickfix.com/files/comment_images/0001/3476/32eebb4f8669b5beb441280bc16f26bf_square.jpeg",
    "representative_image_url": "http://seeclickfix.com/files/comment_images/0001/3476/32eebb4f8669b5beb441280bc16f26bf_square.jpeg",
    "video_url": "http://www.youtube.com/watch?v=dQw4w9WgXcQ"
  }
}

In the event of validation errors

Status: 422 Unprocessable Entity

{
  "errors": {
    "address": [
      "Address can't be blank"
    ],
    "lat": [
      "Lat can't be blank"
    ],
    "lng": [
      "Lng can't be blank"
    ],
    "point": [
      "Point can't be blank",
      "Point Issue is not within boundary of associated request type."
    ],
    "summary": [
      "Summary can't be blank"
    ]
  }
}

If for any reason we decide to hold the report in moderation

We will finish processing the request at a later date.

Status: 202 Accepted

{
  "metadata": {
    "moderated": true
  }
}