API Reference

This section contains the API reference for Goodmap modules.

Core Module

Goodmap engine with location management and admin interface.

goodmap.goodmap.create_app(config_path)

Create Goodmap application from YAML configuration file.

Parameters:

config_path (str) – Path to YAML configuration file

Returns:

Configured Flask application

Return type:

platzky.Engine

goodmap.goodmap.create_app_from_config(config)

Create and configure Goodmap application from config object.

Sets up location models, database queries, CSRF protection, API blueprints, and admin interface based on the provided configuration.

Parameters:

config (GoodmapConfig) – Goodmap configuration object

Returns:

Fully configured Flask application with Goodmap features

Return type:

platzky.Engine

Database Module

goodmap.db.json_file_atomic_dump(data, file_path)

Write JSON data to a file atomically using a temporary file and rename.

Parameters:

• data – Data to serialize as JSON.

• file_path – Destination file path.

class goodmap.db.PaginationHelper

Bases: object

Common pagination utility to eliminate duplication across backends.

static get_sort_key(item, sort_by)

Extract sort key from item for both dict and object types.

static apply_pagination_and_sorting(items, page, per_page, sort_by, sort_order)

Apply sorting and pagination to a list of items.

static apply_filters(items, filters)

Apply filtering based on provided filters dictionary.

static serialize_items(items)

Convert items to dict if needed (for location models).

static create_paginated_response(items, query, extract_filters_func=None)

Create a complete paginated response with all common logic.

class goodmap.db.FileIOHelper

Bases: object

Common file I/O utilities to eliminate duplication.

static read_json_file(file_path)

Read and parse JSON file.

static write_json_file_atomic(data, file_path)

Write JSON data to file atomically.

static get_data_from_file(file_path, data_key='map')

Get data from JSON file with specified key structure.

class goodmap.db.CRUDHelper

Bases: object

Common CRUD operation utilities to eliminate duplication.

static add_item_to_json_db(db_data, collection_name, item_data, default_status=None)

Add item to JSON in-memory database.

static add_item_to_json_file_db(file_path, collection_name, item_data, default_status=None)

Add item to JSON file database.

static add_item_to_mongodb(db_collection, item_data, item_type, default_status=None)

Add item to MongoDB database.

goodmap.db.json_db_get_location_obligatory_fields(db)

Return location obligatory fields from in-memory JSON database.

goodmap.db.json_file_db_get_location_obligatory_fields(db)

Return location obligatory fields from JSON file database.

goodmap.db.google_json_db_get_location_obligatory_fields(db)

Return location obligatory fields from Google Cloud Storage JSON.

goodmap.db.mongodb_db_get_location_obligatory_fields(db)

Return location obligatory fields from MongoDB.

goodmap.db.get_location_obligatory_fields(db)

Dispatch to the backend-specific get_location_obligatory_fields function.

goodmap.db.json_db_get_issue_options(self)

Return reported issue types from in-memory JSON database.

goodmap.db.json_file_db_get_issue_options(self)

Return reported issue types from JSON file database.

goodmap.db.google_json_db_get_issue_options(self)

Return reported issue types from Google Cloud Storage JSON.

goodmap.db.mongodb_db_get_issue_options(self)

Return reported issue types from MongoDB.

goodmap.db.get_issue_options(db)

Dispatch to the backend-specific get_issue_options function.

goodmap.db.google_json_db_get_data(self)

Return map data from Google Cloud Storage JSON.

goodmap.db.json_file_db_get_data(self)

Return map data from JSON file database.

goodmap.db.json_db_get_data(self)

Return map data from in-memory JSON database.

goodmap.db.mongodb_db_get_data(self)

Return map data from MongoDB, including locations and config.

goodmap.db.get_data(db)

Dispatch to the backend-specific get_data function.

goodmap.db.google_json_db_get_visible_data(self)

Retrieve visible data configuration from Google Cloud Storage JSON blob.

Returns:

Dictionary containing field visibility configuration.

Returns empty dict if not found.

Return type:

dict

goodmap.db.json_file_db_get_visible_data(self)

Retrieve visible data configuration from JSON file database.

Returns:

Dictionary containing field visibility configuration.

Returns empty dict if not found.

Return type:

dict

goodmap.db.json_db_get_visible_data(self)

Retrieve visible data configuration from in-memory JSON database.

Returns:

Dictionary containing field visibility configuration.

Returns empty dict if not found.

Return type:

dict

goodmap.db.mongodb_db_get_visible_data(self)

Retrieve visible data configuration from MongoDB.

Returns:

Dictionary containing field visibility configuration.

Returns empty dict if config document not found or field missing.

Return type:

dict

Raises:

• pymongo.errors.ConnectionFailure – If database connection fails.

• pymongo.errors.OperationFailure – If database operation fails.

goodmap.db.get_visible_data(db)

Get the appropriate get_visible_data function for the given database backend.

Parameters:

db – Database instance (must have module_name attribute).

Returns:

Backend-specific get_visible_data function.

Return type:

callable

goodmap.db.google_json_db_get_meta_data(self)

Retrieve metadata configuration from Google Cloud Storage JSON blob.

Returns:

Dictionary containing metadata configuration.

Returns empty dict if not found.

Return type:

dict

goodmap.db.json_file_db_get_meta_data(self)

Retrieve metadata configuration from JSON file database.

Returns:

Dictionary containing metadata configuration.

Returns empty dict if not found.

Return type:

dict

goodmap.db.json_db_get_meta_data(self)

Retrieve metadata configuration from in-memory JSON database.

Returns:

Dictionary containing metadata configuration.

Returns empty dict if not found.

Return type:

dict

goodmap.db.mongodb_db_get_meta_data(self)

Retrieve metadata configuration from MongoDB.

Returns:

Dictionary containing metadata configuration.

Returns empty dict if config document not found or field missing.

Return type:

dict

Raises:

• pymongo.errors.ConnectionFailure – If database connection fails.

• pymongo.errors.OperationFailure – If database operation fails.

goodmap.db.get_meta_data(db)

Get the appropriate get_meta_data function for the given database backend.

Parameters:

db – Database instance (must have module_name attribute).

Returns:

Backend-specific get_meta_data function.

Return type:

callable

goodmap.db.json_db_get_categories(self)

Return category keys from in-memory JSON database.

goodmap.db.json_file_db_get_categories(self)

Return category keys from JSON file database.

goodmap.db.google_json_db_get_categories(self)

Return category keys from Google Cloud Storage JSON.

goodmap.db.mongodb_db_get_categories(self)

Return category keys from MongoDB.

goodmap.db.get_categories(db)

Dispatch to the backend-specific get_categories function.

goodmap.db.json_db_get_category_data(self, category_type=None)

Return category data from in-memory JSON database, optionally filtered by type.

goodmap.db.json_file_db_get_category_data(self, category_type=None)

Return category data from JSON file database, optionally filtered by type.

goodmap.db.google_json_db_get_category_data(self, category_type=None)

Return category data from Google Cloud Storage JSON, optionally filtered by type.

goodmap.db.mongodb_db_get_category_data(self, category_type=None)

Return category data from MongoDB, optionally filtered by type.

goodmap.db.get_category_data(db)

Dispatch to the backend-specific get_category_data function.

goodmap.db.get_location_from_raw_data(raw_data, uuid, location_model)

Find and validate a single location by UUID from raw data.

Parameters:

• raw_data – Dict containing a ‘data’ key with a list of location dicts.

• uuid – UUID string of the location to find.

• location_model – Pydantic model class to validate the location.

Returns:

Validated location model instance, or None if not found.

goodmap.db.google_json_db_get_location(self, uuid, location_model)

Retrieve a single location by UUID from Google Cloud Storage JSON.

goodmap.db.json_file_db_get_location(self, uuid, location_model)

Retrieve a single location by UUID from JSON file database.

goodmap.db.json_db_get_location(self, uuid, location_model)

Retrieve a single location by UUID from in-memory JSON database.

goodmap.db.mongodb_db_get_location(self, uuid, location_model)

Retrieve a single location by UUID from MongoDB.

goodmap.db.get_location(db, location_model)

Dispatch to the backend-specific get_location function.

goodmap.db.get_locations_list_from_raw_data(map_data, query, location_model)

Filter and validate locations from raw map data based on query parameters.

Parameters:

• map_data – Dict containing ‘data’ and ‘categories’ keys.

• query – Dict of query parameters for filtering.

• location_model – Pydantic model class to validate each location.

Returns:

List of validated location model instances.

goodmap.db.google_json_db_get_locations(self, query, location_model)

Retrieve filtered locations from Google Cloud Storage JSON.

goodmap.db.json_file_db_get_locations(self, query, location_model)

Retrieve filtered locations from JSON file database.

goodmap.db.json_db_get_locations(self, query, location_model)

Retrieve filtered locations from in-memory JSON database.

goodmap.db.mongodb_db_get_locations(self, query, location_model)

Retrieve filtered locations from MongoDB.

goodmap.db.get_locations(db, location_model)

Dispatch to the backend-specific get_locations function.

goodmap.db.google_json_db_get_locations_paginated(self, query, location_model)

Google JSON locations with improved pagination.

goodmap.db.json_db_get_locations_paginated(self, query, location_model)

JSON locations with improved pagination.

goodmap.db.json_file_db_get_locations_paginated(self, query, location_model)

JSON file locations with improved pagination.

goodmap.db.mongodb_db_get_locations_paginated(self, query, location_model)

MongoDB locations with improved pagination.

goodmap.db.get_locations_paginated(db, location_model)

Dispatch to the backend-specific get_locations_paginated function.

goodmap.db.json_file_db_add_location(self, location_data, location_model)

Add a new location to the JSON file database.

Raises:

LocationAlreadyExistsError – If a location with the same UUID already exists.

goodmap.db.json_db_add_location(self, location_data, location_model)

Add a new location to the in-memory JSON database.

Raises:

LocationAlreadyExistsError – If a location with the same UUID already exists.

goodmap.db.mongodb_db_add_location(self, location_data, location_model)

Add a new location to MongoDB.

Raises:

LocationAlreadyExistsError – If a location with the same UUID already exists.

goodmap.db.add_location(db, location_data, location_model)

Dispatch to the backend-specific add_location function.

goodmap.db.json_file_db_update_location(self, uuid, location_data, location_model)

Update an existing location in the JSON file database.

Raises:

LocationNotFoundError – If no location with the given UUID exists.

goodmap.db.json_db_update_location(self, uuid, location_data, location_model)

Update an existing location in the in-memory JSON database.

Raises:

LocationNotFoundError – If no location with the given UUID exists.

goodmap.db.mongodb_db_update_location(self, uuid, location_data, location_model)

Update an existing location in MongoDB.

Raises:

LocationNotFoundError – If no location with the given UUID exists.

goodmap.db.update_location(db, uuid, location_data, location_model)

Dispatch to the backend-specific update_location function.

goodmap.db.json_file_db_delete_location(self, uuid)

Delete a location from the JSON file database.

Raises:

LocationNotFoundError – If no location with the given UUID exists.

goodmap.db.json_db_delete_location(self, uuid)

Delete a location from the in-memory JSON database.

Raises:

LocationNotFoundError – If no location with the given UUID exists.

goodmap.db.mongodb_db_delete_location(self, uuid)

Delete a location from MongoDB.

Raises:

LocationNotFoundError – If no location with the given UUID exists.

goodmap.db.delete_location(db, uuid)

Dispatch to the backend-specific delete_location function.

goodmap.db.json_db_add_suggestion(self, suggestion_data)

Add a suggestion to the in-memory JSON database with ‘pending’ status.

goodmap.db.json_file_db_add_suggestion(self, suggestion_data)

Add a suggestion to the JSON file database with ‘pending’ status.

goodmap.db.mongodb_db_add_suggestion(self, suggestion_data)

Add a suggestion to MongoDB with ‘pending’ status.

goodmap.db.google_json_db_add_suggestion(self, suggestion_data)

No-op for Google Cloud Storage JSON (read-only backend).

goodmap.db.add_suggestion(db, suggestion_data)

Dispatch to the backend-specific add_suggestion function.

goodmap.db.json_db_get_suggestions(self, query_params)

Return suggestions from in-memory JSON database, optionally filtered by status.

goodmap.db.json_db_get_suggestions_paginated(self, query)

JSON suggestions with improved pagination.

goodmap.db.json_file_db_get_suggestions(self, query_params)

Return suggestions from JSON file database, optionally filtered by status.

goodmap.db.json_file_db_get_suggestions_paginated(self, query)

JSON file suggestions with improved pagination.

goodmap.db.mongodb_db_get_suggestions(self, query_params)

Return suggestions from MongoDB, optionally filtered by status.

goodmap.db.mongodb_db_get_suggestions_paginated(self, query)

MongoDB suggestions with improved pagination.

goodmap.db.google_json_db_get_suggestions(self, query_params)

Return empty list for Google Cloud Storage JSON (read-only backend).

goodmap.db.google_json_db_get_suggestions_paginated(self, query)

Google JSON suggestions with pagination (read-only).

goodmap.db.get_suggestions(db)

Dispatch to the backend-specific get_suggestions function.

goodmap.db.get_suggestions_paginated(db)

Dispatch to the backend-specific get_suggestions_paginated function.

goodmap.db.json_db_get_suggestion(self, suggestion_id)

Return a single suggestion by UUID from in-memory JSON database.

goodmap.db.json_file_db_get_suggestion(self, suggestion_id)

Return a single suggestion by UUID from JSON file database.

goodmap.db.mongodb_db_get_suggestion(self, suggestion_id)

Return a single suggestion by UUID from MongoDB.

goodmap.db.google_json_db_get_suggestion(self, suggestion_id)

Return None for Google Cloud Storage JSON (read-only backend).

goodmap.db.get_suggestion(db)

Dispatch to the backend-specific get_suggestion function.

goodmap.db.json_db_update_suggestion(self, suggestion_id, status)

Update a suggestion’s status in the in-memory JSON database.

Raises:

ValueError – If no suggestion with the given UUID exists.

goodmap.db.json_file_db_update_suggestion(self, suggestion_id, status)

Update a suggestion’s status in the JSON file database.

Raises:

ValueError – If no suggestion with the given UUID exists.

goodmap.db.mongodb_db_update_suggestion(self, suggestion_id, status)

Update a suggestion’s status in MongoDB.

Raises:

ValueError – If no suggestion with the given UUID exists.

goodmap.db.google_json_db_update_suggestion(self, suggestion_id, status)

No-op for Google Cloud Storage JSON (read-only backend).

goodmap.db.update_suggestion(db, suggestion_id, status)

Dispatch to the backend-specific update_suggestion function.

goodmap.db.json_db_delete_suggestion(self, suggestion_id)

Delete a suggestion from the in-memory JSON database.

Raises:

ValueError – If no suggestion with the given UUID exists.

goodmap.db.json_file_db_delete_suggestion(self, suggestion_id)

Delete a suggestion from the JSON file database.

Raises:

ValueError – If no suggestion with the given UUID exists.

goodmap.db.mongodb_db_delete_suggestion(self, suggestion_id)

Delete a suggestion from MongoDB.

Raises:

ValueError – If no suggestion with the given UUID exists.

goodmap.db.google_json_db_delete_suggestion(self, suggestion_id)

No-op for Google Cloud Storage JSON (read-only backend).

goodmap.db.delete_suggestion(db, suggestion_id)

Dispatch to the backend-specific delete_suggestion function.

goodmap.db.json_db_add_report(self, report_data)

Add a report to the in-memory JSON database.

Raises:

ValueError – If a report with the same UUID already exists.

goodmap.db.json_file_db_add_report(self, report_data)

Add a report to the JSON file database.

Raises:

ValueError – If a report with the same UUID already exists.

goodmap.db.mongodb_db_add_report(self, report_data)

Add a report to MongoDB.

Raises:

ValueError – If a report with the same UUID already exists.

goodmap.db.google_json_db_add_report(self, report_data)

No-op for Google Cloud Storage JSON (read-only backend).

goodmap.db.add_report(db, report_data)

Dispatch to the backend-specific add_report function.

goodmap.db.json_db_get_reports(self, query_params)

Return reports from in-memory JSON database, optionally filtered by status and priority.

goodmap.db.json_db_get_reports_paginated(self, query)

JSON reports with improved pagination.

goodmap.db.json_file_db_get_reports(self, query_params)

Return reports from JSON file database, optionally filtered by status and priority.

goodmap.db.json_file_db_get_reports_paginated(self, query)

JSON file reports with improved pagination.

goodmap.db.mongodb_db_get_reports(self, query_params)

Return reports from MongoDB, optionally filtered by status and priority.

goodmap.db.mongodb_db_get_reports_paginated(self, query)

MongoDB reports with improved pagination.

goodmap.db.google_json_db_get_reports(self, query_params)

Return empty list for Google Cloud Storage JSON (read-only backend).

goodmap.db.google_json_db_get_reports_paginated(self, query)

Google JSON reports with pagination (read-only).

goodmap.db.get_reports(db)

Dispatch to the backend-specific get_reports function.

goodmap.db.get_reports_paginated(db)

Dispatch to the backend-specific get_reports_paginated function.

goodmap.db.json_db_get_report(self, report_id)

Return a single report by UUID from in-memory JSON database.

goodmap.db.json_file_db_get_report(self, report_id)

Return a single report by UUID from JSON file database.

goodmap.db.mongodb_db_get_report(self, report_id)

Return a single report by UUID from MongoDB.

goodmap.db.google_json_db_get_report(self, report_id)

Return None for Google Cloud Storage JSON (read-only backend).

goodmap.db.get_report(db)

Dispatch to the backend-specific get_report function.

goodmap.db.json_db_update_report(self, report_id, status=None, priority=None)

Update a report’s status and/or priority in the in-memory JSON database.

Raises:

ReportNotFoundError – If no report with the given UUID exists.

goodmap.db.json_file_db_update_report(self, report_id, status=None, priority=None)

Update a report’s status and/or priority in the JSON file database.

Raises:

ReportNotFoundError – If no report with the given UUID exists.

goodmap.db.mongodb_db_update_report(self, report_id, status=None, priority=None)

Update a report’s status and/or priority in MongoDB.

Raises:

ReportNotFoundError – If no report with the given UUID exists.

goodmap.db.google_json_db_update_report(self, report_id, status=None, priority=None)

No-op for Google Cloud Storage JSON (read-only backend).

goodmap.db.update_report(db, report_id, status=None, priority=None)

Dispatch to the backend-specific update_report function.

goodmap.db.json_db_delete_report(self, report_id)

Delete a report from the in-memory JSON database.

Raises:

ReportNotFoundError – If no report with the given UUID exists.

goodmap.db.json_file_db_delete_report(self, report_id)

Delete a report from the JSON file database.

Raises:

ReportNotFoundError – If no report with the given UUID exists.

goodmap.db.mongodb_db_delete_report(self, report_id)

Delete a report from MongoDB.

Raises:

ReportNotFoundError – If no report with the given UUID exists.

goodmap.db.google_json_db_delete_report(self, report_id)

No-op for Google Cloud Storage JSON (read-only backend).

goodmap.db.delete_report(db, report_id)

Dispatch to the backend-specific delete_report function.

goodmap.db.extend_db_with_goodmap_queries(db, location_model)

Register all goodmap-specific query functions on the database instance.

Binds backend-specific implementations of all CRUD operations for locations, suggestions, and reports to the given database object.

Parameters:

• db – Database instance to extend with query functions.

• location_model – Pydantic model class used for location validation.

Returns:

The extended database instance.

API Endpoints

goodmap.core_api.get_default_issue_options()

Return hardcoded fallback issue options for backward compatibility.

Deprecated since version 1.5.0: This will be removed in 2.0.0. Configure ‘reported_issue_types’ in the database instead. The hardcoded fallback will be removed in a future release.

goodmap.core_api.make_tuple_translation(keys_to_translate)

goodmap.core_api.get_or_none(data, *keys)

goodmap.core_api.get_locations_from_request(database, request_args)

Shared helper to fetch locations from database based on request arguments.

Parameters:

• database – Database instance

• request_args – Request arguments (flask.request.args)

Returns:

List of locations as basic_info dicts

goodmap.core_api.core_pages(database, languages, notifier_function, csrf_generator, location_model, photo_attachment_class, photo_attachment_config, feature_flags, field_renderers)

Parameters:

• languages (Mapping[str, Mapping[str, str]])

• photo_attachment_class (type[AttachmentProtocol])

• photo_attachment_config (AttachmentConfig)

• feature_flags (FeatureFlagSet)

• field_renderers (dict[str, str])

Return type:

Blueprint