Polygon definitions

Page description

This is an admin/moderator page to which only specific users have access. The page is used to create rules used when importing polygon data from OpenStreetMap into Project-GC. The data is then used for calculations regarding placing geocaches in their correct region/county. The data is also used for rendering maps, as for example the maps in Profile stats.

Country selector

The country selector lists every country available in the Geocaching LIVE api. By selecting a new entry the country is automatically loaded, allow it 1-2 seconds to retrieve its data.

Data shown

In the first section there is basic metadata about the country shown, like the name of the country, and the ID in the API. Then it shows who has created the last definitions of rules and when. On the right side there is a list of region names used by Geocaching.com.

The region names in Project-GC must match those of Geocaching.com. Use relevant rule options to make this happen.

Source site

Project-GC uses OSM-Boundaries.com as a source when importing its polygon data. This site is also a great source to use when building the import rules.

Rules

For Project-GC to know where a country (or region/county) exists in the world it needs the borders. In the most simple cases we can just match a country with an ID in the OpenStreetMap database and it's done. However it's not always that simple, especially for countries. For example the polygon for Finland includes Aland Islands while Aland Islands is its own country according to Geocaching.com. In this case we need to make more advanced rules defining and calculating new polygons in Project-GC.

The rule-set for countries differs a bit from regions/counties, the reason is that a country should always end with a single (multi)polygon, while regions and counties needs one (multi)polygon per region/county.

All import rules are created as JSON-strings. Generally it exists of a list of rules for the polygons itself, and the a list of rules for post-processing names.

You can look at already defined definitions to get an overall understanding how the definitions should look.

Ignore databases

If the OSM data is known to be broken in a specific database version they can be blacklisted with this option.

Just write the name of the database in the input field. If multiple database names are needed, separate them by commas. Use white-space at your own disposal, they will be ignored.

Country rules

All countries must be defined in Project-GC. This is primarily used when rendering maps for Profile stats, but they would look a bit funny if a country was missing.

The country rules are the simplest. There is no post-processing of names and there are only types of rules available.

• includeOsmIds - List of integer IDs from OSM-Boundaries.com. These are IDs of polygons that will be included in the country.
• subtractOsmIds - List of integer IDs from OSM-Boundaries.com. The IDs listed here will be subtracted from the includeOsmIds. For example in the case of Finland, the ID of Finland can be chosen as the country and then Aland Island can be subtracted.

Rather use one big polygon as include and a few subtract than a lot of includes. For example, USA either requires including the whole USA and then subtracting 3-5 polygons, or making a list of ~50 polygons for inclusion. There are two good reasons to rather include the whole country and then make a few subtracts.

• It's faster during the import phase.
• It makes a more readable definition.

The country polygons ignores the names in OpenStreetMap, names from the API will be used instead. This is also why the post-processing rule-set hasn't been implemented.

Example of how to define Norway:

{ "polygons": [ "includeOsmIds":[-2978650],"subtractOsmIds":[-2425963,-1337126,-1337397] ] }

Region rules

When regions exists at Geocaching.com the region names in Project-GC must match these when possible. If they don't, it should clearly be stated in the #Notes -field, and why.

The following keys are allowed when defining regions:

• includeAdminLevels - This is a list where the key is an OSM-ID having a list of administrative levels as a value. An (unrealistic) example where Sweden would have every "län" and every "kommun", and every part of Malmö as a region:

{ "includeAdminLevels": { "-52822": [4, 7], "-935416": [9] } }

• includeIds - Besides including a whole administrative level (that's a child of something) specific OSM-IDs can be included as well. This can sometimes be combined with the above includeAdminLevels. For example if Skåne would belong to Denmark the definition of Denmark would be something similar to:

{ "includeAdminLevels": { "-50046": [4]}, "includeIds": [-54409] }

• excludeIds - Particular OSM-IDs can also be excluded, typically useful if all but a few polygons of an administrative level are to be included. For example, if Skåne in Sweden were to belong to Denmark we could define Sweden's regions as:

{ "includeAdminLevels": { "-52822": [4] }, "excludeIds": [-54409] }

excludeIds only affects polygons coming from includeAdminLevels, therefore this rule will probably be moved inside includeAdminLevels in the future.

• subtractIds - A part of a polygon could also be subtracted if needed. For example, if Malmö didn't belong to Skåne (but to Denmark for example) we could define Sweden's regions as:

{ "includeAdminLevels": { "-52822": [4] }, "subtractIds": [-935416] }

subtractIds only affects polygons coming from includeAdminLevels, therefore this rule will probably be moved inside includeAdminLevels in the future.

• unions - Sometimes we need to create our own polygon for regions/counties as well. Usually to match whatever exists at Geocaching.com. In those cases union can be used. Each child to it should have the name of the region as a key, and then a list of OSM-IDs as a value. There are no options to subtract polygons, everything listed will be included in the union-operation. The example is from New Zealand.

{ "unions": {"North Island":[-2094141,-1790755,-2643819,-1643811,-1638992,-2133870,-1643812,-2094142,-1638991]} }

• nameOverrides - To match the names of Geocaching.com we sometimes needs to rename the polygons coming from OpenStreetMap, for this we can use this option. Use the OSM-ID as key and the new name as value. If we were to rename Skåne to Scania it could look like this:

{ "nameOverrides": {"-54409": "Scania"} }

• removePrefixes - In some cases there are very repetitive prefixes and suffixes used in OpenStreetMap. Again, if the names doesn't match those at Geocaching.com we should make it match. In cases where Geocaching.com doesn't have regions we just want to make it clean and nice. It makes no sense in Project-GC that every region ends with the same suffix, so we remove it. For example in Sweden every/most region ends with "län". Here is how we remove them:

{ "removeSuffixes": ["s län", "län"] }

This example solves both "Hallands län" and "Skåne län" in a correct manner. You do not have to consider any trailing spaces, that's solved automatically by the import scripts.

• removeSuffixes - Remove suffixes works just like #removePrefixes, it's just another key and removes prepending text instead.
• internationalNames - The import scripts defaults to using local region and county names. But we also want to avoid using names that are impossible to write for users who are most familiar with the latin alphabet. So for example when the names are in Asian or Arabic variants we can use this parameter to override the default. But again, in cases where Geocaching.com has regions, it's most important that we match those. It's a boolean option, which defaults to false. Example:

{ "internationalNames": true }

this option.

County rules

The county rules works exactly like the region rules. While nameOverrides exists as an option, it generally shouldn't be used, unless there is a good case for it of course.

Notes

This is a free-text form where you have the option to leave some notes. If there is nothing to say, just leave it empty. But for example when making a subtract it can be worth mentioning what's being subtracted.

Preview data

There is not yet any way to preview the data. Depending on how complex the definitions are it takes hours to calculate new polygons which makes it troublesome to show the moderator some form of preview. Ultimately we should also calculate the number of geocaches included in the polygons, both with old and new definitions - This would be even more expensive.

Historical data

Historical definitions exists in the database but can not yet be viewed on the web. If they are needed due to mistakenly destroying complex definitions we can retrieve them fairly easily.

Priority countries

This is a temporary section which should be updated while work is being made, and finally removed.

On this link you can find some hints of how they have been imported before. It's a similar, but not identical, ruleset.

First priority is every country with region support at Geocaching.com. Secondary is every country which Project-GC already has support for. We can not start using the new code until we are on par with today's live functionality.

• Special countries - These countries today uses another source than OSM, we need to pay extra attention to the difference here.
  • United Kingdom
  • Australia - Unincorporated areas causes problems here.
  • United States
  • New Zealand - Geocaching.com uses regions that doesn't exists. We are recreating them by making a union of other polygons.
  • Canada - The counties used before are from a census database. OSM doesn't have anything usable.