diff options
| -rw-r--r-- | perllib/FixMyStreet/App/Controller/Open311.pm | 217 | ||||
| -rw-r--r-- | templates/web/default/open311/index.html | 147 |
2 files changed, 164 insertions, 200 deletions
diff --git a/perllib/FixMyStreet/App/Controller/Open311.pm b/perllib/FixMyStreet/App/Controller/Open311.pm index a470ae44f..c3ddbfd1a 100644 --- a/perllib/FixMyStreet/App/Controller/Open311.pm +++ b/perllib/FixMyStreet/App/Controller/Open311.pm @@ -51,7 +51,7 @@ Displays some summary information for the requests. sub index : Path : Args(0) { my ( $self, $c ) = @_; - return show_documentation($c); + # don't need to do anything here - should just pass through. } =head2 discovery @@ -86,180 +86,9 @@ sub request_v2 : Regex('^open311(.cgi)?/v2/requests/(\d+).(xml|json|html)$') : A } sub error : Private { - my ($q, $error) = @_; - show_documentation($q, "ERROR: $error"); -} - -sub show_documentation : Private { - my ($c, $message) = @_; - my $jurisdiction_id = 'fiksgatami.no'; - my $response; - - $c->res->content_type('text/html; charset=utf-8'); - - $response .= CGI::h1(_('Open311 API for the mySociety FixMyStreet server')); - $response .= CGI::p(sprintf(_('Note: <strong>%s</strong>'), $message)) - if $message; - $response .= CGI::p(_('At the moment only searching for and looking at reports work.')); - $response .= CGI::p(_('This API implementation is work in progress and not yet stabilized. It will change without warnings in the future.')); - - $response .= CGI::li(CGI::a({rel => 'nofollow', - href => "http://www.open311.org/"}, - _('Open311 initiative web page'))); - $response .= CGI::li(CGI::a({rel => 'nofollow', - href => 'http://wiki.open311.org/GeoReport_v2'}, - _('Open311 specification'))); - - $response .= CGI::p(sprintf(_('At most %d requests are returned in each query. The returned requests are ordered by requested_datetime, so to get all requests, do several searches with rolling start_date and end_date.'), - mySociety::Config::get('RSS_LIMIT'))); - - my $baseurl = $c->cobrand->base_url(); - - $response .= CGI::p(_('The following Open311 v2 attributes are returned for each request: service_request_id, description, lat, long, media_url, status, requested_datetime, updated_datetime, service_code and service_name.')); - - $response .= CGI::p(_('In addition, the following attributes that are not part of the Open311 v2 specification are returned: agency_sent_datetime, title (also returned as part of description), interface_used, comment_count, requestor_name (only present if requestor allowed the name to be shown on this site).')); - - $response .= CGI::p(_('The Open311 v2 attribute agency_responsible is used to list the administrations that received the problem report, which is not quite the way the attribute is defined in the Open311 v2 specification.')); - - my $mapiturl = mySociety::Config::get('MAPIT_URL'); - $response .= CGI::p(sprintf(_('With request searches, it is also possible to search for agency_responsible to limit the requests to those sent to a single administration. The search term is the administration ID provided by <a href="%s">MaPit</a>.'), $mapiturl)); - - $response .= CGI::p(_('Examples:')); - - $response .= "<ul>\n"; - - my @examples = - ( - { - url => "$baseurl/open311.cgi/v2/discovery.xml?jurisdiction_id=$jurisdiction_id", - info => 'discovery information', - }, - { - url => "$baseurl/open311.cgi/v2/services.xml?jurisdiction_id=$jurisdiction_id", - info => 'list of services provided', - }, - { - url => "$baseurl/open311.cgi/v2/services.xml?jurisdiction_id=$jurisdiction_id?lat=11&long=60", - info => 'list of services provided for WGS84 coordinate latitude 11 longitude 60', - }, - { - url => "$baseurl/open311.cgi/v2/requests/1.xml?jurisdiction_id=$jurisdiction_id", - info => 'Request number 1', - }, - { - url => "$baseurl/open311.cgi/v2/requests.xml?jurisdiction_id=$jurisdiction_id&status=open&agency_responsible=1601&end_date=2011-03-10", - info => 'All open requests reported before 2011-03-10 to Trondheim (id 1601)', - }, - { - url => "$baseurl/open311.cgi/v2/requests.xml?jurisdiction_id=$jurisdiction_id&status=open&agency_responsible=219|220", - info => 'All open requests in Asker (id 220) and Bærum (id 219)', - }, - { - url => "$baseurl/open311.cgi/v2/requests.xml?jurisdiction_id=$jurisdiction_id&service_code=Vannforsyning", - info => "All requests with the category 'Vannforsyning'", - }, - { - url => "$baseurl/open311.cgi/v2/requests.xml?jurisdiction_id=$jurisdiction_id&status=closed", - info => 'All closed requests', - }, - ); - for my $example (@examples) { - my $url = $example->{url}; - my $info = $example->{info}; - my $googlemapslink = ''; - if ($url =~ m%/requests.xml%) { - my $rssurl = $url; - $rssurl =~ s/.xml/.rss/; - my $encurl = CGI::escape($rssurl); - $googlemapslink = ' [ ' . - CGI::a({href => "http://maps.google.com/?q=$encurl"}, - _('GeoRSS on Google Maps')) . ' ]'; - } - $response .= CGI::li(CGI::a({href => $url}, $info) . $googlemapslink . '<br>' . - ent($url)); - } - - $response .= <<EOF; -</ul> - -<h2>Searching</h2> - -<p>The following search parameters can be used:</p> - -<dl> - -<dt>service_request_id</dt> -<dd>Search for numeric ID of specific request. - Using this is identical to asking for a individual request using - the /requests/number.format URL.</dd> -<dt>service_code</dt> -<dd>Search for the given category / service type string.</dd> - -<dt>status</dt> -<dd>Search for open or closed (fixed) requests.</dd> - -<dt>start_date<dt> -<dd>Only return requests with requested_datetime set after or at the - date and time specified. The format is YYYY-MM-DDTHH:MM:SS+TZ:TZ.</dd> - -<dt>end_date<dt> -<dd>Only return requests with requested_datetime set before the date - and time specified. Same format as start_date.</dd> - -<dt>agency_responsible</dt> -<dd>ID of government body receiving the request. Several IDs can be - specified with | as a separator.</dd> - -<dt>interface_used<dt> -<dd>Name / identifier of interface used.</dd> - -<dt>has_photo<dt> -<dd>Search for entries with or without photos. Use value 'true' to -only get requests created with images, and 'false' to get those -created without images.</dd> - -<dt>max_requests</dt> -<dd>Max number of requests to return from the search. If it is larger -than the site specific max_requests value specified in the discovery -call, the value provided is ignored.</dd> - -<dl> - -<p>The search result might look like this:</p> - -EOF - - $response .= xml_format(" - <requests> - <request> - <agency_responsible> - <recipient>Statens vegvesen region øst</recipient> - <recipient>Oslo</recipient> - </agency_responsible> - <agency_sent_datetime>2011-04-23T10:28:55+02:00</agency_sent_datetime> - <description>Mangler brustein: Det støver veldig på tørre dager. Her burde det vært brustein.</description> - <detail>Det støver veldig på tørre dager. Her burde det vært brustein.</detail> - <interface_used>Web interface</interface_used> - <lat>59.916848</lat> - <long>10.728148</long> - <requested_datetime>2011-04-23T09:32:36+02:00</requested_datetime> - <requestor_name>Petter Reinholdtsen</requestor_name> - <service_code>Annet</service_code> - <service_name>Annet</service_name> - <service_request_id>1</service_request_id> - <status>open</status> - <title>Mangler brustein</title> - <updated_datetime>2011-04-23T10:28:55+02:00</updated_datetime> - </request> - </requests> -"); - - $c->stash->{response} = $response; -} - -sub xml_format : Private { - my $xml = shift; - return '<pre>' . ent($xml) . '</pre>'; + my ($c, $error) = @_; + $c->stash->{error} = "ERROR: $error"; + $c->stash->{template} = 'open311/index.html'; } # Example @@ -466,7 +295,7 @@ sub output_requests : Private { sub get_requests : Private { my ($c, $format) = @_; - return unless is_jurisdiction_id_ok($c); + $c->forward( 'is_jurisdiction_id_ok' ); my %rules = ( service_request_id => 'id = ?', @@ -497,10 +326,10 @@ sub get_requests : Private { my @valuelist; for my $agency (split(/\|/, $value[0])) { unless ($agency =~ m/^(\d+)$/) { - error ($c, + $c->detach( 'error', [ sprintf(_('Invalid agency_responsible value %s'), - $value[0])); - return; + $value[0]) + ] ); } my $agencyid = $1; # FIXME This seem to match the wrong entries @@ -526,10 +355,10 @@ sub get_requests : Private { $criteria .= ' and photo is null'; @value = (); } else { - error($c, + $c->detach( 'error', [ sprintf(_('Incorrect has_photo value "%s"'), - $value[0])); - return; + $value[0]) + ] ); } } elsif ('interface_used' eq $param) { if ('Web interface' eq $value[0]) { @@ -566,7 +395,7 @@ sub get_requests : Private { # http://seeclickfix.com/open311/requests/1.xml?jurisdiction_id=sfgov.org sub get_request : Private { my ($c, $id, $format) = @_; - return unless is_jurisdiction_id_ok($c); + $c->forward( 'is_jurisdiction_id_ok' ); my $criteria = "state IN ('fixed', 'confirmed') AND id = ?"; if ('html' eq $format) { @@ -586,18 +415,17 @@ sub format_output : Private { $c->res->content_type('application/xml; charset=utf-8'); $c->stash->{response} = XMLout($hashref, RootName => undef); } else { - error($c, sprintf(_('Invalid format %s specified.'), $format)); - return; + $c->detach( 'error', [ + sprintf(_('Invalid format %s specified.'), $format) + ] ); } } sub is_jurisdiction_id_ok : Private { - my ($c) = @_; + my ( $self, $c ) = @_; unless (my $jurisdiction_id = $c->req->param('jurisdiction_id')) { - error($c, _('Missing jurisdiction_id')); - return 0; + $c->detach( 'error', [ _('Missing jurisdiction_id') ] ); } - return 1; } # Input: 2011-04-23 10:28:55.944805< @@ -613,17 +441,6 @@ sub w3date : Private { return $datestr; } -sub end : Private { - my ( $self, $c ) = @_; - - my $response = - $c->stash->{error} - ? { error => $c->stash->{error} } - : $c->stash->{response}; - - $c->res->body( $response || {} ); -} - =head1 AUTHOR Copyright (c) 2011 Petter Reinholdtsen, some rights reserved. diff --git a/templates/web/default/open311/index.html b/templates/web/default/open311/index.html new file mode 100644 index 000000000..aee6650ec --- /dev/null +++ b/templates/web/default/open311/index.html @@ -0,0 +1,147 @@ +[% INCLUDE 'header.html', title => 'Open311' %] + +<h1>[% loc('Open311 API for the mySociety FixMyStreet server') %]</h1> + +[% IF error %] +<p>[% tprintf( loc('Note: <strong>%s</strong>'), error ) %]</p> +[% END %] + +<p>[% loc('At the moment only searching for and looking at reports work.') %]</p> +<p>[% loc('This API implementation is work in progress and not yet stabilized. It will change without warnings in the future.') %]</p> + +<ul> +<li><a rel="nofollow" href="http://www.open311.org/">[% loc('Open311 initiative web page') %]</a></li> +<li><a rel="nofollow" href="http://wiki.open311.org/GeoReport_v2">[% loc('Open311 specification') %]</a></li> +</ul> + +<p>[% tprintf( loc('At most %d requests are returned in each query. The returned requests are ordered by requested_datetime, so to get all requests, do several searches with rolling start_date and end_date.'), c.config.RSS_LIMIT ) %]</p> + +<p>[% loc('The following Open311 v2 attributes are returned for each request: service_request_id, description, lat, long, media_url, status, requested_datetime, updated_datetime, service_code and service_name.') %]</p> + +<p>[% loc('In addition, the following attributes that are not part of the Open311 v2 specification are returned: agency_sent_datetime, title (also returned as part of description), interface_used, comment_count, requestor_name (only present if requestor allowed the name to be shown on this site).') %]</p> + +<p>[% loc('The Open311 v2 attribute agency_responsible is used to list the administrations that received the problem report, which is not quite the way the attribute is defined in the Open311 v2 specification.') %]</p> + +<p>[% tprintf( loc('With request searches, it is also possible to search for agency_responsible to limit the requests to those sent to a single administration. The search term is the administration ID provided by <a href="%s">MaPit</a>.'), c.config.MAPIT_URL ) %]</p> + +<p>[% loc('Examples:') %]</p> + +<ul> + +[% jurisdiction_id = 'fiksgatami.no' %] +[% examples = [ + { + url = c.cobrand.base_url _ "/open311/v2/discovery.xml?jurisdiction_id=$jurisdiction_id", + info = 'discovery information', + }, + { + url = c.cobrand.base_url _ "/open311/v2/services.xml?jurisdiction_id=$jurisdiction_id", + info = 'list of services provided', + }, + { + url = c.cobrand.base_url _ "/open311/v2/services.xml?jurisdiction_id=$jurisdiction_id?lat=11&long=60", + info = 'list of services provided for WGS84 coordinate latitude 11 longitude 60', + }, + { + url = c.cobrand.base_url _ "/open311/v2/requests/1.xml?jurisdiction_id=$jurisdiction_id", + info = 'Request number 1', + }, + { + url = c.cobrand.base_url _ "/open311/v2/requests.xml?jurisdiction_id=$jurisdiction_id&status=open&agency_responsible=1601&end_date=2011-03-10", + info = 'All open requests reported before 2011-03-10 to Trondheim (id 1601)', + }, + { + url = c.cobrand.base_url _ "/open311/v2/requests.xml?jurisdiction_id=$jurisdiction_id&status=open&agency_responsible=219|220", + info = 'All open requests in Asker (id 220) and Bærum (id 219)', + }, + { + url = c.cobrand.base_url _ "/open311/v2/requests.xml?jurisdiction_id=$jurisdiction_id&service_code=Vannforsyning", + info = "All requests with the category 'Vannforsyning'", + }, + { + url = c.cobrand.base_url _ "/open311/v2/requests.xml?jurisdiction_id=$jurisdiction_id&status=closed", + info = 'All closed requests', + }, +] %] +[% FOREACH examples %] + <li><a href="[% url %]">[% info %]</a> + [% IF url.match('/requests.xml') %] + [ <a href="http://maps.google.com/?q=[% url.replace('.xml', '.rss') | uri %]">[% loc('GeoRSS on Google Maps') %]</a> ] + [% END %] + <br>[% ent(url) %]</li> +[% END %] + +</ul> + +<h2>Searching</h2> + +<p>The following search parameters can be used:</p> + +<dl> + +<dt>service_request_id</dt> +<dd>Search for numeric ID of specific request. + Using this is identical to asking for a individual request using + the /requests/number.format URL.</dd> +<dt>service_code</dt> +<dd>Search for the given category / service type string.</dd> + +<dt>status</dt> +<dd>Search for open or closed (fixed) requests.</dd> + +<dt>start_date<dt> +<dd>Only return requests with requested_datetime set after or at the + date and time specified. The format is YYYY-MM-DDTHH:MM:SS+TZ:TZ.</dd> + +<dt>end_date<dt> +<dd>Only return requests with requested_datetime set before the date + and time specified. Same format as start_date.</dd> + +<dt>agency_responsible</dt> +<dd>ID of government body receiving the request. Several IDs can be + specified with | as a separator.</dd> + +<dt>interface_used<dt> +<dd>Name / identifier of interface used.</dd> + +<dt>has_photo<dt> +<dd>Search for entries with or without photos. Use value 'true' to +only get requests created with images, and 'false' to get those +created without images.</dd> + +<dt>max_requests</dt> +<dd>Max number of requests to return from the search. If it is larger +than the site specific max_requests value specified in the discovery +call, the value provided is ignored.</dd> + +<dl> + +<p>The search result might look like this:</p> + +<pre>[% " + <requests> + <request> + <agency_responsible> + <recipient>Statens vegvesen region øst</recipient> + <recipient>Oslo</recipient> + </agency_responsible> + <agency_sent_datetime>2011-04-23T10:28:55+02:00</agency_sent_datetime> + <description>Mangler brustein: Det støver veldig på tørre dager. Her burde det vært brustein.</description> + <detail>Det støver veldig på tørre dager. Her burde det vært brustein.</detail> + <interface_used>Web interface</interface_used> + <lat>59.916848</lat> + <long>10.728148</long> + <requested_datetime>2011-04-23T09:32:36+02:00</requested_datetime> + <requestor_name>Petter Reinholdtsen</requestor_name> + <service_code>Annet</service_code> + <service_name>Annet</service_name> + <service_request_id>1</service_request_id> + <status>open</status> + <title>Mangler brustein</title> + <updated_datetime>2011-04-23T10:28:55+02:00</updated_datetime> + </request> + </requests> +" | html %]</pre> + +[% INCLUDE 'footer.html' %] + |