[% INCLUDE 'header.html', title = 'Open311', bodyclass = 'twothirdswidthpage' %]

[% INCLUDE 'about/_sidebar.html' %]

<h1>FixMyStreet support for Open311</h1>

<p>FixMyStreet supports Open311 both as a <a href="#client">client</a> (sending
reports made on the site to an external service via the Open311 protocol), and
partly as a <a href="#server">server</a> (returning reports made on the site when
queried via the Open311 protocol).</p>

<dl id="client">

<dt>What is Open311?</dt>

<dd>
<p>In a nutshell, it's an international open standard that allows services to
'talk to' council systems.</p>
<p>As channels of communication diversify, it has become more and more
important that council systems can recognise and accept reports from a variety
of sources. For example, reports may come in via Twitter, SMS, email, services
like FixMyStreet, and the council's own website.</p>
</dd>

<dt>Where can I find out more?</dt>

<dd>
<p>Open311 isn't as widely known as it deserves to be, so we wrote a
<a href="http://www.mysociety.org/2013/01/10/open311-introduced/">short
series of blog posts</a> to explain the basics. And you can find out lots more at
<a href="http://open311.org/">open311.org</a>.</p>
</dd>

<dt>Why does it matter?</dt>

<dd>
<p>If you oversee problem reports at a council, you will of course be concerned
about future-proofing your communication channels in an easy and economical way
&ndash; Open311 gives you that assurance.</p>

[% IF c.cobrand.moniker == 'fixmystreet' %]
<p>You may be interested to know about <a
href="https://www.fixmystreet.com/council">FixMyStreet
for Councils</a>, our hosted service which sits seamlessly on your council
website.</p>

<p>We can integrate it with any council back-end system, but if you use
Open311, we charge less. That's how much we believe it's the sane way forward
for council problem-reporting systems.</p>
[% END %]

<dt>Any questions?</dt>

<dd>
<p>We're always happy to talk. Just <a href="/contact">drop us a line</a>.</p>
</dd>

</dl>

<hr>

<h2 id="server">[% loc('Open311 API for the mySociety FixMyStreet server') %]</h2>

[% 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.OPEN311_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 = c.cobrand.jurisdiction_id_example %]
[% 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=60&long=11",
        info = 'list of services provided for WGS84 coordinate latitude 60 longitude 11',
    },
    {
        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>
    <br>[% url | html %]</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' %]