settings module: Basic definitions and settings

Basic definitions for the use of various geolocation web-services.

Description

This module contains some basic definitions (classes and variables) that are used for:

• query and collection through Eurostat GISCO webservices,
• query and collection through external GIS webservices,
• simple geographical data handling and geospatial processing.

Note

The classes exposed in this module (i.e., type class happyType and logging classes happyVerbose, happyWarning, happyError) can be ignored at the first glance since they are not strictly requested to run the services. They are provided here for the sake of an exhaustive documentation.

Dependencies

require: sys, warnings, six, inspect, collection, itertools, functools

Contents

settings.CODER_GEONAME = 'GeoNames'

Default geocoder used when the generic geopy package (see website geopy) is run for connecting to the “external” (all but GISCO) web-services.

settings.CODER_GISCO = 'GISCO'

Identifier of GISCO geocoder.

settings.CODER_GOOGLE = 'GoogleV3'

Identifier of GISCO geocoder.

settings.CODER_GOOGLE_MAPS = 'GMaps'

Identifier of Google Maps geocoder.

settings.CODER_GOOGLE_PLACES = 'GPlace'

Identifier of Google Places geocoder.

settings.CODER_LIST = ['GISCO', 'GoogleV3', 'GMaps', 'GPlace']

List of geocoders available.

settings.CODER_OSM = 'osm'

Identifier of Open Street Map geocoder.

settings.CODER_PROJECTIONS = {'GISCO': 4326, 'GMaps': 'EPSG3857', 'GPlace': 'EPSG3857', 'GoogleV3': 'EPSG3857'}

Default geographical projections available with the different geocoders.

settings.DEF_DRIVER_NAME = 'ESRI Shapefile'

Geospatial Data Abstraction Library (GDAL) driver name.

settings.DEF_GISCO_FORMAT = 'geojson'

Default format for GISCO vector datasets.

settings.DEF_GISCO_LEVEL = 0

Default NUTS background level.

settings.DEF_GISCO_PROJECTION = 4326

Default projection used by GISCO services.

settings.DEF_GISCO_SCALE = '60m'

Default scale for GISCO vector datasets.

settings.DEF_GISCO_TILE = 'osmec'

Default GISCO background tile.

settings.DEF_GISCO_TILEPROJ = 3857

Default GISCO background tile projection.

settings.DEF_GISCO_VECTOR = 'RG'

Default spatial typology.

settings.DEF_GISCO_YEAR = 2016

Default year considered for NUTS background datasets (not the most recent, but up-to-date).

settings.DEF_GISCO_ZOOM = 4

Default zooming value in map displays.

settings.DEF_LANG = 'en'

Default language used when launching Eurostat GISCO API.

settings.DEF_NUTS2JSON_FORMAT = 'topojson'

Default format for Nuts2json vector datasets.

settings.DEF_NUTS2JSON_PROJECTION = 3857

Default projection used by Nuts2json services.

settings.DEF_NUTS2JSON_SCALE = '60m'

Default map dimension (in pixel).

settings.DEF_PROTOCOL = 'https'

Default protocol used by the APIs.

settings.EC_DOMAIN = 'europa.eu'

Domain of European Commission generic web-services.

settings.EC_URL = 'ec.europa.eu'

URL of the European Commission website.

settings.ESTAT_DOMAIN = 'eurostat'

Domain of Eurostat website under European Commission URL.

settings.ESTAT_URL = 'https://ec.europa.eu/eurostat'

Complete URL of Eurostat website.

settings.EU_AGGREGATES = {'CACO': ['ME', 'MK', 'AL', 'RS', 'TR'], 'EFTA': ['IS', 'LI', 'NO', 'CH'], 'EU27': ['BE', 'BG', 'CZ', 'DK', 'DE', 'EE', 'IE', 'EL', 'ES', 'FR', 'HR', 'IT', 'CY', 'LV', 'LT', 'LU', 'HU', 'MT', 'NL', 'AT', 'PL', 'PT', 'RO', 'SI', 'SK', 'FI', 'SE'], 'EU28': ['BE', 'BG', 'CZ', 'DK', 'DE', 'EE', 'IE', 'EL', 'ES', 'FR', 'HR', 'IT', 'CY', 'LV', 'LT', 'LU', 'HU', 'MT', 'NL', 'AT', 'PL', 'PT', 'RO', 'SI', 'SK', 'FI', 'SE', 'UK']}

ISO-codes of countries (Member States) in the EU and other euro area aggregates; see this page.

settings.EU_GEOCENTRE = [50.033333, 10.35]

//en.wikipedia.org/wiki/Gädheim>`_ (in the district of Haßberge in Bavaria) serves as the geographical centre of the European Union (when the United Kingdom leaves on April 2019).

See the Wikipedia page on the geographical midpoint of Europe for discussions on the topic. For the determination of the actual geographical coordinates (50°02′N 10°21′E), see also this page.

Type:The German municipality of `Gädheim <https

settings.GISCO2GDAL_DRIVERS = {'geojson': {'driver': 'GeoJSON', 'options': ['RFC7946=YES', 'WRITE_BBOX=YES']}, 'shp': {'driver': 'ESRI Shapefile', 'options': None}}

Driver and translate options between GISCO disseminated dataset formats and Geospatial Data Abstraction Library (GDAL) accepted formats.

settings.GISCO_ARCGIS = 'webgate.ec.europa.eu/estat/inspireec/gis/arcgis/rest/services/'

GISCO ArcGIS server.

settings.GISCO_CACHEDOMAIN = 'eurostat/cache/GISCO/distribution/v2'

Domain of cache database, e.g. countries and NUTS background vector datasets themes, for download/distribution.

settings.GISCO_CACHEURL = 'ec.europa.eu/eurostat/cache/GISCO/distribution/v2'

Complete URL of GISCO cache database.

settings.GISCO_CTRYDOMAIN = 'countries'

Subdomain of countries.

settings.GISCO_CTRYTHEME = 'countries'

NUTS theme used for URL naming.

settings.GISCO_CTRYURL = 'ec.europa.eu/eurostat/cache/GISCO/distribution/v2/countries'

Complete URL of countries download/distribution services.

settings.GISCO_DATA_DIMENSIONS = ['SOURCE', 'YEAR', 'PROJECTION', 'SCALE', 'VECTOR', 'LEVEL', 'IFORMAT']

Descriptors/parameters used to define a given GISCO dataset, e.g. a NUTS or a country file.

settings.GISCO_DATA_INPUT = ['UNIT', 'FILE', 'URL', 'LAYER', 'FEATURE', 'GEOMETRY', 'RESPONSE', 'CONTENT']

Type/nature of data parsing a given GISCO dataset, e.g. a NUTS or a country file.

settings.GISCO_FORMATS = {'csv': 'csv', 'geojson': 'geojson', 'pbf': 'pbf', 'shp': 'shx', 'topojson': 'json'}

Format of GISCO vector data files.

settings.GISCO_LAUDOMAIN = 'documents/345175/501971'

settings.GISCO_LAUURL = 'https://ec.europa.eu/eurostat/documents/345175/501971'

Complete URL of GISCO LAU resources.

settings.GISCO_LEVELS = [0, 1, 2, 3]

Levels of NUTS background areas.

settings.GISCO_NUTSDOMAIN = 'nuts'

Subdomain of NUTS background.

settings.GISCO_NUTSTHEME = 'nuts'

NUTS theme used for URL naming.

settings.GISCO_NUTSURL = 'ec.europa.eu/eurostat/cache/GISCO/distribution/v2/nuts'

Complete URL of NUTS background download/distribution services.

settings.GISCO_PATTERNS = {'bulk': {'compress': 'zip', 'domain': 'download'}, 'country': {'base': 'CNTR_', 'bulk': 'ref-countries-', 'domain': 'distribution', 'fmt': 'json', 'info': 'countries-{year}-units', 'theme': 'countries'}, 'distribution': {'base': '', 'domain': 'eurostat/cache/GISCO/distribution/v2'}, 'nuts': {'base': 'NUTS_', 'bulk': 'ref-nuts-', 'domain': 'distribution', 'fmt': 'json', 'info': 'nuts-{year}-units', 'theme': 'nuts'}, 'nutsid': {'fmt': 'csv', 'info': 'NUTS_AT_{year}'}}

download for

bulk datasets or distribution for single areas,

• name and type of the file storing all nuts unit datasets,
• name and type of the file storing all country unit datasets,
• Name and type of the file storing the correspondance table between NUTS names

and their IDs.

Type:

String patterns used to define

Type:

• domains of the services used for theme vector datasets

settings.GISCO_PROJECTIONS = {'EPSG3035': 3035, 'EPSG3857': 3857, 'EPSG4258': 4258, 'EPSG4326': 4326, 'ETRS89': 4258, 'LAEA': 3035, 'Mercator': 3857, 'WGS84': 4326, 'laea': 3035, 'longlat': 4258, 'merc': 3857}

Projections and EPSG codes currently supported by GISCO services. See http://spatialreference.org for the list of all EPSG codes and corresponding spatial references.

settings.GISCO_RESTDOMAIN = 'rest/gisco/'

Domain of GISCO REST webservices and webtools.

settings.GISCO_RESTURL = 'europa.eu/webtools/rest/gisco/'

Complete URL of GISCO REST webservices and webtools.

settings.GISCO_SCALES = {1: '01m', 3: '03m', 10: '10m', 20: '20m', 60: '60m'}

scale Million) of vector datasets.

Type:Scale (1

settings.GISCO_TILEDOMAIN = 'webtools/maps/tiles'

Domain of GISCO background tiling service.

settings.GISCO_TILEORDER = '{z}/{y}/{x}'

GISCO background tile ordering (used for visualisation).

settings.GISCO_TILES = {'bmarble': {'attr': '© NASA’s Earth Observatory', 'bckgrd': 'bmarble', 'label': 'Blue marble mosaic of Earth', 'proj': True}, 'boundaries': {'attr': '© Eurogeographics @UN-FAO @Turkstat', 'bckgrd': 'countryboundaries_world', 'label': 'boundaries of all countries', 'proj': True}, 'citynames': {'attr': '© Eurogeographics', 'bckgrd': 'citynames_europe', 'label': 'names of settlement', 'proj': True}, 'cloudless': {'attr': 'Sentinel Cloudless', 'bckgrd': 'sentinelcloudless', 'label': 'Sentinel Cloudless', 'proj': False}, 'coast': {'attr': '© EC-GISCO', 'bckgrd': 'coast', 'label': 'continental outlines', 'proj': True}, 'copernicus': {'attr': '© Core003 Mosaic', 'bckgrd': 'copernicus003', 'label': 'Copernicus Core003', 'proj': False}, 'countrynames': {'attr': '© Eurogeographics', 'bckgrd': 'countrynames_europe', 'label': 'European country names', 'proj': True}, 'gray': {'attr': '© Natural Earth', 'bckgrd': 'gray', 'label': 'gray shaded relief of Earth', 'proj': True}, 'graybg': {'attr': '© Eurogeographics', 'bckgrd': 'gray-bg', 'label': 'boundaries on gray background', 'proj': True}, 'hypso': {'attr': '© Natural Earth', 'bckgrd': 'hypso', 'label': 'climate shaded relief of Earth', 'proj': True}, 'natural': {'attr': '© Natural Earth', 'bckgrd': 'natural', 'label': 'landcover shaded relief of Earth', 'proj': True}, 'osmec': {'attr': '© OpenStreetMap', 'bckgrd': 'osm-ec', 'label': 'OpenStreetMap', 'proj': False}, 'roadswater': {'attr': '© Eurogeographics', 'bckgrd': 'roadswater_europe', 'label': 'cities, roads and rivers', 'proj': True}}

Dictionary for the various GISCO background tiles service. See the list of available tiles servers.

settings.GISCO_TILEURL = 'europa.eu/webtools/maps/tiles'

Complete URL of GISCO background tiling service.

settings.GISCO_VECTORS = {'boundary': 'BN', 'label': 'LB', 'line': 'BN', 'region': 'RG'}

Dictionary of spatial typologies, i.e. the vector features of GISCO datasets.

settings.GISCO_WEBDOMAIN = 'webtools'

Domain of GISCO web-service under the European Commission URL.

settings.GISCO_YEARS = [2003, 2006, 2010, 2013, 2016]

Years of adoption/revision of NUTS background areas.

settings.HTTP_ERROR_STATUS = {100: {'desc': 'Continue with the request.', 'name': 'Continue'}, 101: {'desc': 'Server is switching to a different protocol.', 'name': 'Switching Protocols'}, 102: {'desc': 'Server has received and is processing the request, but no response is available yet.', 'name': 'Processing'}, 200: {'desc': 'Request was successful.', 'name': 'OK'}, 201: {'desc': 'Request was successful, and a new resource has been created.', 'name': 'Created'}, 202: {'desc': 'Request has been accepted but not yet acted upon.', 'name': 'Accepted'}, 203: {'desc': 'Request was successful, but server is returning information that may be from another source.', 'name': 'Non-Authoritative Information'}, 204: {'desc': 'There is no content to send for this request, but the headers may be useful.', 'name': 'No Content'}, 205: {'desc': 'Server successfully processed the request, but is not returning any content.', 'name': 'Reset Content'}, 206: {'desc': 'Download is separated into multiple streams, due to range header.', 'name': 'Partial Content'}, 207: {'desc': 'Message body that follows is an XML message and can contain a number of separate response codes.', 'name': 'Multi-Status'}, 208: {'desc': 'Response is a representation of the result of one or more instance-manipulations applied to the current instance.', 'name': 'Already Reported'}, 226: {'desc': 'The server has fulfilled a GET request for the resource, and the response is a representation of the result of one or more instance-manipulations applied to the current instance.', 'name': 'IM Used'}, 300: {'desc': 'Request has more than one possible response.', 'name': 'Multiple Choices'}, 301: {'desc': 'URI of this resource has changed.', 'name': 'Moved Permanently'}, 302: {'desc': 'URI of this resource has changed, temporarily.', 'name': 'Found'}, 303: {'desc': 'Client should get this resource from another URI.', 'name': 'See Other'}, 304: {'desc': 'Response has not been modified, client can continue to use a cached version.', 'name': 'Not Modified'}, 305: {'desc': 'Requested resource may only be accessed through a given proxy.', 'name': 'Use Proxy'}, 306: {'desc': 'No longer used. Requested resource may only be accessed through a given proxy.', 'name': 'Switch Proxy'}, 307: {'desc': 'URI of this resource has changed, temporarily. Use the same HTTP method to access it.', 'name': 'Temporary Redirect'}, 308: {'desc': 'The request, and all future requests should be repeated using another URI.', 'name': 'Permanent Redirect'}, 400: {'desc': 'Server could not understand the request, due to invalid syntax.', 'name': 'Bad Request'}, 401: {'desc': 'Authentication is needed to access the given resource.', 'name': 'Unauthorized'}, 402: {'desc': 'Some form of payment is needed to access the given resource.', 'name': 'Payment Required'}, 403: {'desc': 'Client does not have rights to access the content.', 'name': 'Forbidden'}, 404: {'desc': 'Server cannot find requested resource.', 'name': 'Not Found'}, 405: {'desc': 'Server has disabled this request method and cannot be used.', 'name': 'Method Not Allowed'}, 406: {'desc': 'Requested resource is only capable of generating content not acceptable according to the Accept headers sent.', 'name': 'Not Acceptable'}, 407: {'desc': 'Authentication by a proxy is needed to access the given resource.', 'name': 'Proxy Authentication Required'}, 408: {'desc': 'Server would like to shut down this unused connection.', 'name': 'Request Timeout'}, 409: {'desc': 'Request could not be processed because of conflict in the request, such as an edit conflict.', 'name': 'Conflict'}, 410: {'desc': 'Requested content has been delected from the server', 'name': 'Gone'}, 411: {'desc': 'Server requires the Content-Length header to be defined.', 'name': 'Length Required'}, 412: {'desc': 'Client has indicated preconditions in its headers which the server does not meet.', 'name': 'Precondition Failed'}, 413: {'desc': 'Request entity is larger than limits defined by server.', 'name': 'Request Entity Too Large'}, 414: {'desc': 'URI requested by the client is too long for the server to handle.', 'name': 'Request-URI Too Long'}, 415: {'desc': 'Media format of the requested data is not supported by the server.', 'name': 'Unsupported Media Type'}, 416: {'desc': "Range specified by the Range header in the request can't be fulfilled.", 'name': 'Requested Range Not Satisfiable'}, 417: {'desc': "Expectation indicated by the Expect header can't be met by the server.", 'name': 'Expectation Failed'}, 418: {'desc': 'HTCPCP server is a teapot; the resulting entity body may be short and stout.', 'name': "I'm a Teapot"}, 419: {'desc': 'Authentication Timeout.', 'name': 'Authentication Timeout'}, 422: {'desc': 'Request was well-formed but was unable to be followed due to semantic errors.', 'name': 'Unprocessable Entity'}, 423: {'desc': 'Resource that is being accessed is locked.', 'name': 'Locked'}, 424: {'desc': 'Request failed due to failure of a previous request (e.g. a PROPPATCH).', 'name': 'Failed Dependency'}, 426: {'desc': 'Client should switch to a different protocol such as TLS/1.0.', 'name': 'Upgrade Required'}, 428: {'desc': 'Origin server requires the request to be conditional.', 'name': 'Precondition Required'}, 429: {'desc': 'User has sent too many requests in a given amount of time.', 'name': 'Too Many Requests'}, 431: {'desc': 'Server rejected the request because either a header, or all the headers collectively, are too large.', 'name': 'Header Fields Too Large'}, 440: {'desc': 'Your session has expired. (Microsoft)', 'name': 'Login Timeout'}, 444: {'desc': 'Server has returned no information to the client and closed the connection (Ngnix).', 'name': 'No Response'}, 449: {'desc': 'Request should be retried after performing the appropriate action (Microsoft).', 'name': 'Retry With'}, 450: {'desc': 'Windows Parental Controls are turned on and are blocking access to the given webpage.', 'name': 'Blocked By Windows Parental Controls'}, 451: {'desc': 'You attempted to access a Legally-restricted Resource. This could be due to censorship or government-mandated blocked access.', 'name': 'Unavailable For Legal Reasons'}, 494: {'desc': 'Nginx internal code', 'name': 'Request Header Too Large'}, 495: {'desc': 'SSL client certificate error occurred.', 'name': 'Cert Error'}, 496: {'desc': 'Client did not provide certificate.', 'name': 'No Cert'}, 497: {'desc': 'Plain HTTP request sent to HTTPS port.', 'name': 'HTTP to HTTPS'}, 499: {'desc': 'Connection has been closed by client while the server is still processing its request.', 'name': 'Client Closed Request'}, 500: {'desc': "Server has encountered a situation it doesn't know how to handle.", 'name': 'Internal Server Error'}, 501: {'desc': 'Request method is not supported by the server and cannot be handled.', 'name': 'Not Implemented'}, 502: {'desc': 'Server, while working as a gateway to get a response needed to handle the request, got an invalid response.', 'name': 'Bad Gateway'}, 503: {'desc': 'Server is not yet ready to handle the request.', 'name': 'Service Unavailable'}, 504: {'desc': 'Server is acting as a gateway and cannot get a response in time.', 'name': 'Gateway Timeout'}, 505: {'desc': 'HTTP version used in the request is not supported by the server.', 'name': 'HTTP Version Not Supported'}, 506: {'desc': 'Transparent content negotiation for the request results in a circular reference.', 'name': 'Variant Also Negotiates'}, 507: {'desc': 'Server is unable to store the representation needed to complete the request.', 'name': 'Insufficient Storage'}, 508: {'desc': 'The server detected an infinite loop while processing the request', 'name': 'Loop Detected'}, 510: {'desc': 'Further extensions to the request are required for the server to fulfill it.', 'name': 'Not Extended'}, 511: {'desc': 'The client needs to authenticate to gain network access.', 'name': 'Network Authentication'}}

//en.wikipedia.org/wiki/List_of_HTTP_status_codes.

Type:Descriptions of HTTP status codes. See https

settings.KEY_GISCO = None

Dummy GISCO key. It is set to None since connection to GISCO web-services does not require authentication.

settings.KEY_GOOGLE = 'key'

Personal key used for connecting to the various Google web-services.

settings.KEY_OSM = None

Dummy Open Street Map key (connection to Open Street Map web-services does not require authentication).

settings.LANGS = ('en', 'de', 'fr')

Languages supported by this package.

settings.NUTS2JSON_DOMAIN = 'raw.githubusercontent.com/eurostat/Nuts2json/gh-pages'

Domain of Nuts2json database.

settings.NUTS2JSON_FORMATS = {'geojson': 'json', 'topojson': 'json'}

Format of Nuts2json vector data files.

settings.NUTS2JSON_PROJECTIONS = {'EPSG3035': 3035, 'EPSG3857': 3857, 'EPSG4258': 4258, 'EPSG4326': 4326, 'ETRS89': 4258, 'LAEA': 3035, 'Mercator': 3857, 'WGS84': 4326, 'laea': 3035, 'longlat': 4258, 'merc': 3857}

Projections and encoding strings currently supported by Nuts2json service (for dissemination). See http://spatialreference.org for the list of all EPSG codes and corresponding spatial references.

settings.NUTS2JSON_SCALES = {1: '01m', 3: '03m', 10: '10m', 20: '20m', 60: '60m'}

Map dimension (in pixel) adopted for the fetching of Nuts2json. Currently, all maps are squared.

settings.NUTS2LAU = {2013: {2010: 'EU-28_2010.xlsx', 2011: 'EU-28_2011.xlsx', 2012: 'EU-28_2012.xlsx', 2013: 'EU-28_2013.xlsx', 2014: 'EU-28_2014.xlsx', 2015: 'EU-28_2015.xlsx', 2016: 'EU-28_LAU_2016', 2017: 'EU-28_LAU_2017_NUTS_2013.xlsx'}, 2016: {2017: 'EU-28_LAU_2017_NUTS_2016.xlsx', 2018: 'EU-28-LAU-2018-NUTS-2016.xlsx'}}

Conversion tables between LAU and NUTS datasets.

settings.OSM_URL = 'nominatim.openstreetmap.org/'

Open Street Map web-service complete URL.

settings.POLYLINE = False

Boolean flag set to import the package polylines that will enable you to generate polylines (see the package website). Not really necessary to generate the routes.

settings.PROTOCOLS = ('http', 'https', 'ftp')

Recognised protocols (APIs, bulk downloads,…).