This program simulates the CitySourced back-end API. It follows the CitySourced API as closely as possible (there are some differences!).
The Simulator reads the initial data set from the "data.json" file. Once running, data additions and modifications (e.g. new reports created by calls to "CreateThreeOneOne") are appended to the initial set.
This is based on the limited CitySource docs available in their Knowledge Base.
To run, simply copy and unzip the appropriate program file and the two JSON files (config.json and data.json) to a suitable directory. You may need to set permissions on Linux/MacOS ("chmod 777 CSSimulator"). If you're running on MacOS or Linux, start the program in the standard *nix way: "./CSSimulator {command line options}".
Endpoint | Description |
---|---|
http://localhost:<port> |
"intro" description |
http://localhost:<port>/docs |
displays this documentation |
http://localhost:<port>/api |
API endpoint. Messages formated as per the City Sourced KB must be POSTed to this URL |
- The system runs as "localhost". The port number can be specified on the command line (see Command Line Options below), or in the "config.json" file. The command line will override the config.json setting.
- The system reads the initial data from the "data.json" file. Edit this file to create any test data you wish to have initially available at system start.
- Tip: you can get Lat/Lng easily by: finding the address in Google Maps, right clicking on the map pin (or any location), and selecting "What's here?".
- New reports (created by calling request "CreateThreeOneOne") are kept in memory until the Simulator is stopped. They are not saved back to the data.json file.
- Any newly created reports are fully searchable.
- The XML elements are not necessarily returned in the same order as in the CitySourced API... this is typical XML, and there is not an XSD in the CitySourced docs specifying the XML elements be in a particular order. Your unmarshaler should be ok with this..
- This currently only supports XML output. JSON output can be added if needed.
- There are zip files for the various runtime environments:
- CSSimulator_mac.zip - MacOS.
- CSSimulator_win.zip - Window.
- CSSimulator_linux.zip - Linux.
- Each zip file contains the following files:
Option | Description |
---|---|
-port={portnum} | Run on the specified port number. The default port number is 5050. The port can also be set in the config.json file. |
-debug | Activates debug printing to the console. |
Filename: "config.json". The "api" object contains the mock CitySourced API "key". It is currently set to "a01234567890z". This key is present as the first XML element in every API request. The "server" object contains the port setting. This can be overridden at the command line using the "-port=xxx" syntax.
Filename: "data.json". The file contains two primary objects: "reports" and "comments". These should be self explanatory based on the CitySourced API docs.
The Simulator supports the following CitySourced API calls.
CitySourced KB: CreateThreeOneOne() - implemented
CitySourced KB: CreateThreeOneOneComent() - implemented
Creates a comment for a specified Report.
CitySourced KB: CreateThreeOneOneMedia() - NOT IMPLEMENTED
The CitySourced documentation is unclear - is this a multi-part request (XML and Binary image in the same request), or does this request return a URL to which the image is subsequently uploaded?
CitySourced KB: CreateThreeOneOneVote() - implemented
This creates a single upvote for the specified report.
CitySourced KB: UpdateThreeOneOne() - implemented
Updates the Ticket information attached to the report. We assume this comes from the agency servicing the report, and would not be called by the mobile device.
One field is updated: TicketSla
This call is confusing, as the example references only the "TicketId" as any sort of identifier. We will assume that this is the ReportID.
CitySourced KB: GetReport() - implemented
Get a specific report using the Report ID.
The following requests can return zero or more reports. The number of reports can be limited by:
- MaxResults
- DateRangeStart
- DateRangeEnd
CitySourced KB: GetReportsByAddress() - implemented
This function first reaches out to the Google Geocode API and converts the specified address to Lat/Lng. Then GetReportsByLatLng() is called to return the reports that are within the specified search radius.
CitySourced KB: GetReportsByAuthorId - NOT IMPLEMENTED
There does not appear to be an AuthorID in the CreateThreeOneOne() call, so it is unclear how to implement this request.
CitySourced KB: CitySourced KB: GetReportsByDeviceId - implemented
Get reports created by the specified Device ID. This searches only on the value of <DeviceId>
- the <DeviceType>
and <DeviceModel>
fields are ignored.
CitySourced KB: GetReportsByLatLng() - implemented
Get all reports that within a specified distance (in meters) from the specified coordinate. The routine uses the Haversine distance method using this Go code.
To limit by MaxResults, the result set is first filtered by distance from the search point ascending, and the limited. In other words, the reports closest to the search point will be returned.
Limitations
- The GeoCoderType parameter is ignored.
- Coordinates must be in the typical Decimal Degrees WGS84 Compliant format, as you would get if you right click on Google Maps and select "What's here?". For example, San Jose City Hall is: (37.337930, -121.885891).
CitySourced KB: GetReportsByZipCode() - implemented
Gets reports matching the specified Zip Code.
- CreateMobileDevice() - purpose and usage of this call is unclear from the City Sourced docs.
- GetReportsByAuthorId()
- CreateThreeOneOneMedia()