Polygon definitions
Contents
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.
All import rules are created as a JSON-string. Note that while keys that are positive integers don't have to be quoted, negative integers must.
Valid:
{123: []}
Invalid:
{-123: []}
Valid:
{"-123": []}
You can look at already defined definitions to get an overall understanding how the definitions should look.
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.[1]
Country rules supports two kinds of keys only:
- includeIds - List of integer IDs from OSM-Boundaries.com. These are IDs of polygons that will be included in the country.
- subtractIds - List of integer IDs from OSM-Boundaries.com. The IDs listed here will be subtracted from the includeIds. 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.
Example of how to define Norway:
{"includeIds":[-2978650],"subtractIds":[-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 of 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] }
- 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] }
- 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. Example:
{ "internationalNames": true }
It's a boolean option, which defaults to false.
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.
- Region support at Geocaching.com
- Ireland
- Belgium
- Switzerland
- Australia
- Netherlands
- United Kingdom
- Canada
- Japan
- Mexico
- Italy
- Brazil
- Norway
- Austria
- United States - This country should be fixed so that it proceeds from admin-level 2 and then exclude things, instead of including 50 items.
- France
- Region support at Project-GC - For most of these Project-GC should have information of what admin-levels were used a long time ago.
- Mauritania
- Ethiopia
- Niger
- Aland Islands
- Turkey
- Oman
- Madagascar
- Colombia
- Saint Helena
- Azerbaijan
- Indonesia
- Somalia
- Gambia
- Guadeloupe
- Equatorial Guinea
- Romania
- Argentina
- Luxembourg
- Iceland
- Singapore
- Curaçao
- Peru
- Djibouti
- Ghana
- Gabon
- Cameroon
- Bosnia and Herzegovina
- Martinique
- Libya
- Egypt
- Morocco
- Guernsey
- Namibia
- Denmark
- Algeria
- Ecuador
- Qatar
- Burkina Faso
- Senegal
- Tunisia
- India
- Rwanda
- Tanzania
- Democratic Republic of the Congo
- Lithuania
- Latvia
- Ukraine
- Bulgaria
- Dominican Republic
- Cuba
- Syria
- Malawi
- Cyprus
- Chad
- Uganda
- Malta
- Zimbabwe
- Mozambique
- Lesotho
- Jordan
- Maldives
- Isle of Man
- Belarus
- Liberia
- Georgia
- Moldova
- Burundi
- Angola
- Greece
- Sudan
- Slovenia
- Montenegro
- Andorra
- Nigeria
- Malaysia
- Albania
- Chile
- Kenya
- Mauritius
- US Virgin Islands
- Russia
- Réunion
- Puerto Rico
- Cabo Verde
- Swaziland
- North Macedonia
- Botswana
- Sierra Leone
- Zambia
- Croatia
- Faroe Islands
- Sao Tome and Principe
- Taiwan
- China
- Mali
- Finland
- Estonia
- Serbia
- Liechtenstein
- Philippines
- Armenia
- Benin
- Vietnam
- Kazakhstan
- Israel
- United Arab Emirates
- Bahrain
- Thailand
- Laos
- Hong Kong
- Special countries - These countries today uses another source than OSM, we need to pay extra attention to the difference here.
- United Kingdom
- Australia
- 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.
Notes
- ↑ Only true for the upcoming maps of Profile stats.
