diff options
Diffstat (limited to 'docs/customising/boundaries.md')
| -rw-r--r-- | docs/customising/boundaries.md | 459 |
1 files changed, 459 insertions, 0 deletions
diff --git a/docs/customising/boundaries.md b/docs/customising/boundaries.md new file mode 100644 index 000000000..d48a472aa --- /dev/null +++ b/docs/customising/boundaries.md @@ -0,0 +1,459 @@ +--- +layout: page +title: Admin boundaries +--- + +# Admin boundaries and FixMyStreet + +<p class="lead"> + When you set up FixMyStreet, you usually need to provide <strong>admin boundaries</strong> + for each of the + <a href="{{ "/glossary/#body" | relative_url }}" class="glossary__link">bodies</a> + you'll be sending reports to. If you're lucky, the boundaries might already + be available. If not, you'll have to make them. This page explains your + options. +</p> + +## Why FixMyStreet needs boundaries + +When someone sticks a pin in the map to report a problem, FixMyStreet uses +boundaries to answer the question: _who is responsible for fixing problems +**here**_? + +This also means that boundaries can be used to determine if the pin has +been put somewhere that is *not* covered by any bodies. + +<div class="attention-box"> + We've written a separate page about + <a href="{{ "/customising/fms_and_mapit/" | relative_url }}">how FixMyStreet uses MapIt</a>, + which is the service that determines which area any point (pin) is within. It's + helpful to understand how that works — because it also explains how + FixMyStreet determines which categories of problem can be reported at any + location — but the rest of this page is about making and using the boundaries that + FixMyStreet needs. +</div> + +FixMyStreet finds all the bodies that are associated with the area (or areas) +that the pin is inside -- those are the bodies to whom the report might be sent. +Which of these bodies is actually chosen depends on the +<a href="{{ "/glossary/#category" | relative_url }}" class="glossary__link">category</a> +the user selects when they complete their problem report. + +## Boundaries are independent of your maps! + +**Boundaries are not really anything to do with maps** — they exist +independently of the maps you're using (although, of course, both are about +geography). FixMyStreet shows the map *before* the user clicks on it to place +the pin. It doesn't check the boundaries until *after* the pin has been placed. + +## Every body must be associated with an area + +So if you're setting up FixMyStreet to run in your region, you *must* provide +these boundaries to FixMyStreet. Once you've done this, you can associate the +bodies you'll be sending reports to with these areas. This is easy to do in +the FixMyStreet admin: you simply choose the area (or areas) from a drop-down +list when you create or edit the body. + +## Where to get your boundary data from + +If the bodies you are going to be sending reports to are local government +departments, it's possible that this data already exists. We use the admin +boundary data from +<a href="{{ "/glossary/#osm" | relative_url }}" class="glossary__link">OpenStreetMap</a>, +and many countries' data is already available. If that's the case for you, then +this is going to be easy! You just have to identify the areas you need, and +tell FixMyStreet to ignore all the others. + +But if the boundaries you need are not already in Open Street Map -- maybe +nobody has ever put them in, or maybe your government doesn't publish such data +for people to use, or perhaps the areas your bodies use are not admin +boundaries anyway -- you'll have to create your own. + +## The geometry of boundaries + +Areas often don't overlap -- because it's common for local government to +arrange its jurisdiction so that each has its own area to cover. + +But actually the MapIt service is very flexible, and you can have areas that +overlap, or be entirely separate and never touch, or even contain all or part +of one another. This is because all FixMyStreet really cares about is asking +MapIt "which areas is this pin in?" MapIt may reply with none, one, or many +areas, depending on how your boundaries are arranged. + +Note that more than one body can cover the same area (actually it’s quite +common). For example, two national bodies (the Highways Department and the +Water Department) might both have the same national boundary data. + +Also, it's possible to associate a body in FixMyStreet with more than +one area from MapIt. For example, a single port authority could be associated +with the ports on three different islands. + + +## Types of boundaries + +The type of boundary data you need depends on a number of factors, but will +probably be one of these: + + * ["Everywhere"](#everywhere) -- you can run FixMyStreet without a specific boundary + * [Simple approximate area](#approx-area) -- that is, just one area around the place you need + * [Simple approximate areas](#approx-areas) -- as above, but for multiple areas + * [Accurate OpenStreetMap data](#mysociety-mapit) -- the preferred option + * [Accurate data that isn't on OSM](#accurate) -- if you have your own boundary data, for example + +If you're not sure which is for you, read through the sections below. + +<!-- TODO add diagrams! Did some Isle of Wight ones but I don't like 'em --> + +<a name="everywhere"> </a> + +## "Everywhere" + +This is the simplest boundary: it's infinte, so anywhere the user clicks is +inside the area called "everywhere". + +Use this type of boundary if: + + * the bodies you're sending reports to don't depend on the whereabouts of the problem + * or all the problem reports are always sent to the same, single body + * you don't mind that FixMyStreet will never reject any problem report because it's too far away + +The advantage of using the boundary "Everywhere" is that it's very easy to set +up. The disadvantage is that your FixMyStreet will accept clicks *anywhere* on +the map. This may be acceptable if you are limiting your +<a href="{{ "/glossary/#geocoder" | relative_url }}" class="glosssary">geocoder</a> +to a very specific area. + +<dl class="reveal-on-click" data-reveal-noun="details"> + <dt> + <h3>How to set this up</h3> + </dt> + <dd> + <p> + This is the default setup of a new FixMyStreet installation (if you used the + <a href="{{ "/install/install-script" | relative_url }}">installation script</a> or the + <a href="{{ "/install/ami" | relative_url }}">AMI install</a>). + </p> + <p> + Set + <code><a href="{{ "/customising/config/#mapit_url" | relative_url }}">MAPIT_URL</a></code> + to be blank, and set + <code><a href="{{ "/customising/config/#mapit_types" | relative_url }}">MAPIT_TYPES</a></code> + to the special value <code>ZZZ</code>. FixMyStreet will use a fake MapIt that always + returns "Everywhere" as the only area that contains the point — for any + location. + </p> + <p> + Your <code>conf/general.yml</code> file should contain this: + </p> +<pre><code>MAPIT_URL: '' +MAPIT_TYPES: ['ZZZ'] +MAPIT_ID_WHITELIST: [ ] +</code></pre> + </dd> +</dl> + +<a name="approx-area"> </a> + +## Simple approximate area + +Sometimes you just need a boundary to broadly determine if a pin in the map is +too far away from the single area you're receiving reports for. + +Use this type of boundary if you: + + * don't need an accurate boundary (for example, _"anything roughly near the town centre is OK"_) + * do want to prevent problem reports for locations that are not within this area + +<dl class="reveal-on-click" data-reveal-noun="details"> + <dt> + <h3>How to set this up</h3> + </dt> + <dd> + <p> + You need to install your own MapIt instance, and add the area to that. The + MapIt admin interface (which uses the Django framework) lets you click-and-draw + a polygon over a map. Alternatively, we run a MapIt server for custom areas + like this, so — especially if you are just doing this as a probationary + trial — we may be able to host this for you (note though that we do + rate-limit calls to MapIt). Either send us + <a href="{{ "/glossary/#kml" | relative_url }}" class="glossary__link">KML shape files</a>, + or if you can't do that, maybe a clear image of the map with the boundary + drawn on it for us to copy. + </p> + <p> + In your <code>conf/general.yml</code>, you must set + <code><a href="{{ "/customising/config/#mapit_url" | relative_url }}">MAPIT_URL</a></code> + to either your MapIt or our custom one, and set + <code><a href="{{ "/customising/config/#mapit_types" | relative_url }}">MAPIT_TYPES</a></code> + to the areas you want (the actual values will depend on what that particular + MapIt is returning). You should also set + <code><a href="{{ "/customising/config/#mapit_id_whitelist" | relative_url }}">MAPIT_ID_WHITELIST</a></code> + to the ID of the single area you want. + </p> + <pre><code>MAPIT_URL: 'http://mapit.example.com' +MAPIT_TYPES: ['CITY'] +MAPIT_ID_WHITELIST: [ 133 ] +</code></pre> + </dd> +</dl> + +<a name="approx-areas"> </a> + +## Simple approximate areas + +This is the same as the previous example, but shows that you can have multiple +areas. This works best if they don't need to be very accurate — that is, +no colinear borders. + +Use this type of boundary if you: + + * don't need an accurate boundary (e.g. anything roughly in an area is OK) + * the boundaries don't adjoin, or are very simple (no crinkly edges) + * do want to prevent problem reports for locations that are not within these areas + +<dl class="reveal-on-click" data-reveal-noun="details"> + <dt> + <h3>How to set this up</h3> + </dt> + <dd> + <p> + Same as previous example: either set up your own instance of MapIt, or ask to + have your boundaries added to our custom one. If you want us to host it, we'll + need <a href="{{ "/glossary/#kml" | relative_url }}" class="glossary__link">KML shape files</a> + or a graphic showing the boundary clearly shown so we can copy it. + </p> + <p> + Note that now there may be more than one type of area, and you'll need to explicitly + nominate every area you're interested in with + <code><a href="{{ "/customising/config/#mapit_id_whitelist" | relative_url }}">MAPIT_ID_WHITELIST</a></code> + (unless you want *all* the areas this MapIt returns for the given type, in + which case you can set it to be empty). + </p> + <pre><code>MAPIT_URL: 'http://mapit.example.com' +MAPIT_TYPES: ['CITY', 'COUNTY'] +MAPIT_ID_WHITELIST: [ 133, 145, 12, 80 ] +</code></pre> + </dd> +</dl> + +<a name="mysociety-mapit"> </a> + +## Accurate OpenStreetMap data + +It's possible that the admin boundaries of local government in your area are +already available in the OpenStreetMap project. If this is the case, +FixMyStreet can automatically use them. **This is the easiest solution if the +data you need is there** because we already run two servers +([UK MapIt](https://mapit.mysociety.org) and +[global MapIt](http://global.mapit.mysociety.org)) +that make this data available. + +Use this type of boundary if: + + * the boundary data for the areas you need is already on OpenStreetMap + +<dl class="reveal-on-click" data-reveal-noun="details"> + <dt> + <h3>How determine if the boundary data is available</h3> + </dt> + <dd> + <p> + Start by finding the <a href="{{ "/glossary/#latlong" | relative_url }}" + class="glossary__link">lat-long</a> of some of the places you want to cover, + and look them up on <a href="http://global.mapit.mysociety.org">global + MapIt</a> (or maybe the <a href="https://mapit.mysociety.org">UK one</a>). + If you see the "Areas covering this point" include the admin + boundaries you need, you're good to go! For example, here's + the <a + href="http://global.mapit.mysociety.org/point/4326/10.75,59.95.html">page + for Oslo, in Norway</a>. + </p> + <p> + Note that our MapIt servers' data may lag a little behind OSM, so + if it's not there, look on the + <a href="http://www.openstreetmap.org">OpenStreetMap website</a> just in + case it's been added since MapIt's last update. If so, let us + know, and we'll pull it in for you. + </p> + <p> + Here's an example of the steps to follow to find the data you need + to use global MapIt. This example uses Zurich as an example city. + </p> + <ol> + <li> + <p> + Go to <a href="http://nominamtim.openstreetmap.org">OpenStreetMap's + geocoder</a> and enter the name of the city, e.g., "Zurich, + Switzerland". + </p> + </li> + <li> + <p> + Check that's found the right place (and, if you want, check the map + is how you expected). Click on the <strong>details</strong> link just + below the name of the top hit. The details page lists lots of data, + including the centre point (lat/long values that will look something + like <code>-34.9059039,-56.1913569</code>).</p></li> <li><p>Go to <a + href="http://global.mapit.mysociety.org">global MapIt</a> and paste + those lat/long values into the text input. + </p> + </li> + <li> + <p> + MapIt will show you all the <a + href="http://global.mapit.mysociety.org/point/4326/8.55,47.366667.html">admin boundaries</a> + that contain that point. You're interested in + the ones that relate to bodies that serve those areas. For example, + if a district council fixes the potholes in that district. + Specifically, you need the <strong>Administrative Boundary + Levels</strong> (which will look like <code>O04</code> or + <code>O05</code>), which are the values for your + <code><a href="{{ "/customising/config/#mapit_types" | relative_url }}">MAPIT_TYPES</a></code>. + Remember this data is boundary data from OpenStreetMap — + if the boundaries you need are not shown, you may have to set up your + own (described below). You can also click on any of the boundaries + listed on MapIt to see the areas they actually cover on the map. + </p> + </li> + <li> + <p> + The individual <em>area_id</em>s are also useful, because you put + them into the <code><a href="{{ "/customising/config/#mapit_id_whitelist" | relative_url }}">MAPIT_ID_WHITELIST</a></code>. + </p> + </li> + </ol> + </dd> + <dt> + <h3>Using our MapIt servers: some restrictions</h3> + </dt> + <dd> + <p> + We run two public MapIt services: <a + href="https://mapit.mysociety.org">mapit.mysociety.org</a> covers the UK + (because that's where we're based, and it serves our own + <a href="www.fixmystreet.com">UK FixMySteet</a> site), and + <a href="http://global.mapit.mysociety.org">global.mapit.mysociety.org</a>, + which covers the whole world. The data we use for global MapIt is from + <a href="http://www.openstreetmap.org">OpenStreetMap</a>, so if someone has + put administrative boundary data for your country into OSM, before too + long global MapIt will have it too. + </p> + <p> + Please get in touch with us if you are expecting to generate a lot of + requests or <strong>if you are using it commercially</strong>. We + rate-limit calls to MapIt, so if your site gets really busy, you should + set up your own instance (we can help you, and the <a + href="https://github.com/mysociety/mapit">code is on GitHub</a>). But when + you're setting your site up to begin with, you can usually get it running + using one of our MapIt servers. + </p> + </dd> + <dt> + <h3>How to set this up</h3> + </dt> + <dd> + <p> + In your <code>conf/general.yml</code> file, point + <code><a href="{{ "/customising/config/#mapit_url" | relative_url }}">MAPIT_URL</a></code> + at the global MapIt server. + </p> + <p> + Find the areas you need by looking on the + <a href="http://global.mapit.mysociety.org">global MapIt website</a> or the + <a href="https://mapit.mysociety.org">UK one</a>. You must also nominate + the types of area these are (effectively the <em>level</em> of admin + boundary it is), and the generation. On global, the area types look + something like <code>[ 'O05', 'O06' ]</code>. (Note those contain capital + letter O followed by digits). To determine what types you need, look for + the codes marked “Administrative Boundary Levels” that MapIt + returns — for example, here's + <a href="http://global.mapit.mysociety.org/point/4326/8.55,47.366667.html">global + MapIt's data for Zurich</a>. + </p> + <p> + The UK MapIt types are different. For example, for UK FixMyStreet, we use: + </p> +<pre><code>MAPIT_TYPES: [ 'DIS', 'LBO', 'MTD', 'UTA', 'CTY', 'COI', 'LGD' ] +</code></pre> + <p> + which covers all the UK council types (for example, <code>DIS</code> is district council, + <code>CTY</code> is county council). + </p> + <p> + Finally, limit your installation to the specific areas you're interested + in (otherwise you'll be getting areas from the whole world). Identify the + specific areas you want to use, and list them explicitly in + <code><a href="{{ "/customising/config/#mapit_id_whitelist" | relative_url }}">MAPIT_ID_WHITELIST</a></code>. + You should also set + <code><a href="{{ "/customising/config/#mapit_generation" | relative_url }}">MAPIT_GENERATION</a></code>, + so that your areas can still be found when we update the global MapIt data. + </p> +<pre><code>MAPIT_URL: 'http://global.mapit.mysociety.org' +MAPIT_TYPES: ['O06','O07'] +MAPIT_ID_WHITELIST: ['12345','345432','978638'] +MAPIT_GENERATION: 3 +</code></pre> + + </dd> + +</dl> + +<a name="accurate"> </a> + +## Accurate data that isn't on OSM + +Use this type of boundary if: + + * you need accurate boundaries because the different bodies that + solve problems in your region serve specific areas that are geometrically + complex and/or are precisely adjacent + * the boundary data for the areas you need are not already on OpenStreetMap + * but you do have access to this data from some other source + +This means you have to source the data yourself -- either by getting your local +government to release it, or else drawing it yourself. Then you need to import +this data into a MapIt server and use that. + +<dl class="reveal-on-click" data-reveal-noun="details"> + <dt> + <h3>How to set this up</h3> + </dt> + <dd> + <p> + Ideally, if you can source the data from your local government (which + means it's definitive), then it's great if you can add it (as + admin boundary data) to the OpenStreetMap project. Our global MapIt will + subsequently import it and your FixMyStreet can then use it as described + in the previous example. If you're going to do that, <strong>the + data must be open data</strong> and you should probably ask about it on + the <a href="http://lists.openstreetmap.org/listinfo/imports">OSM import + list</a> first. Of course, if you do this then anyone else in the world + who wants the data will be able to use it too, which is why we encourage + this approach. + </p> + <p> + But if you can't do that, or the boundary data you have is not + definitive, you can create your own. Use any good GIS software to plot + the boundaries accurately, and then export it as + <a href="{{ "/glossary/#kml" | relative_url }}" class="glossary__link">KML shape files</a>. + MapIt can import these, so you can then either run your own MapIt + instance, or ask us to add it to our custom one. + </p> + </dd> +</dl> + +## Can you see the boundaries? + +FixMyStreet doesn't normally display the admin areas and boundaries on the maps +(mainly because most users really don't care — they just want to report +a problem). But it *is* possible, with some customisation, to change this +behaviour. + +If you just want to see a boundary drawn on a map to check that it's covering +the area you want, you can see this by going to the MapIt server it's on, and +looking at that area's HTML page. For example, see the [boundary for +Norway](http://global.mapit.mysociety.org/area/363186.html) on the global MapIt +server. + + + |