Geocoder to geocoder3 migration

During initial migration of geocoder project to geocoder3 many changes in structure and approach was made. Here is list of noticeable changes, that should be considered during migration from geocoder to geocoder3. Also, please read changes in described in project releases section.

Some parts of text below describe new provider’s approach. This is valid only to providers, that are marked as Geocoder3 ready in main readme.md file.

Default geocoding engine changed from Google to OpenStreetMap

As Google engine now requires mandatory API key, default engine changed to free OpenStreetMap.

Some helper functions removed from api.py and project

Functions for ‘silence’ geocoding or IP geocoding are removed from project. Please use exact provider and provider configuration for such requests. Functions itself located in api.py.

List of removed functions:

  • geocoder.elevation()

  • geocoder.nokia() - now called as geocoder.here()

  • geocoder.location() - replaced with geocoder.Location, direct class sharing

  • geocoder.places()

  • geocoder.reverse()

  • geocoder.timezone()

Provider’s files relocated

All provider’s definition files relocated from project main folder to providers module and related subdirectory inside. Directories structure respect provider implementation function.

If you use direct provider classes imports, please update import statements. If you use direct helper’s functions from geocoder module - no changes expected.

geocoder.base.OneResult changes

  • Property self.raw renamed to self.object_raw_json to be more explainable in inside content. This change affects all subclasses (all providers).

  • Property self.housenumber renamed to self.house_number. Affect all nested provider’s files. Property self.house_number removed and available only in concrete provider’s implementation.

  • Most default properties values replaced from empty string "" to None. Empty dicts in some cases left untouched. Please verify properties signatures.

  • List of default properties become much smaller, some secondary properties, not required to internal geocoder.base.OneResult work was removed. This will allow new providers faster implementation. Such properties may exist in concrete implementations. Removed:

    • accuracy

    • quality

    • house_number

    • street

    • city

    • state

    • country

    • postal

    • osm

    • locality

    • province

    • street_number

    • road

    • route

  • All parts of geocoder.base.OneResult now have huge docstrings and documentation, explaining all behaviour and approach.

  • Some internal instance variables and properties renamed to be more concrete. This affect all children classes. List of renames:

    • json to object_json

geocoder.base.MultipleResultsQuery changes

  • Class will enforce correct setting of cls._URL, cls._RESULT_CLASS, cls._METHOD, cls._PROVIDER in nested classes on project initialization stage.

  • Non-mandatory class variables cls.method and cls.provider renamed to cls._METHOD, cls._PROVIDER and become mandatory, related tests added.

  • Internal class structure changed. Now geocoder.base.MultipleResultsQuery.__init__() does not make an external query, and only do object initialization. This allow to initialize any amount of objects in advance usage cases (in loops). Query made in geocoder.base.MultipleResultsQuery.__call__() method. This change does not change helpers behaviour. I.e. geocoder.get_results() and related functions already respect this change internally.

  • Some internal instance variables and properties renamed to be more concrete. This affect all children classes. List of renames:

    • response to raw_response

    • _list to results_list

    • ok to has_data

  • New instance variables/properties added:

    • is_called - Hold status of external request. I.e. was or not was made.

    • raw_json - Hold unmodified JSON from provider for whole answer.

  • Removed functions:

    • geocoder.base.MultipleResultsQuery.set_default_result()

  • geocoder.base.MultipleResultsQuery.__init__() method now have all default keyword arguments in signature, removing silent usage of kwargs.get("something"), this practice will be extended to all child classes.

  • All parts of geocoder.base.MultipleResultsQuery now have huge docstrings and documentation, explaining all behaviour and approach.

All print statements replaced with logging module

List of affected files, functions and classes:

Removed(some temporary) project features

  • OSM type CLI/Debug output removed as non-well documented

kwargs approach and naming changes

  • There was a confusion between ‘deprecated’ limit and new maxRows provider’s setting. All such cases renamed to self-explained max_results.

  • Everywhere, where it was possible all **kwargs replaced with complete list of function settings, usually with expected input type and defaults, if defaults available.

geocoder.providers.google classes renamed

  • geocoder.providers.ElevationQuery to geocoder.providers.GoogleElevationQuery

  • geocoder.providers.PlacesQuery to geocoder.providers.GooglevPlacesQuery

  • geocoder.providers.ElevationResult to geocoder.providers.GoogleElevationResult

  • geocoder.providers.PlacesResult to geocoder.providers.GooglevPlacesResult