Core Functions

create_poster()

Generate a complete map poster with roads, water, parks, and typography.

create_poster(
    city,
    country,
    point,
    dist,
    output_file,
    output_format,
    width=12,
    height=16,
    country_label=None,
    name_label=None,
    display_city=None,
    display_country=None,
    fonts=None,
)

Creates a high-quality poster by fetching OpenStreetMap data, rendering map layers, applying the current theme, and adding text labels with coordinates.

str

required

City name for display on poster

str

required

Country name for display on poster

tuple

required

(latitude, longitude) tuple for map center

int

required

Map radius in meters (e.g., 4000-6000m for small cities, 15000-20000m for large metros)

str

required

Path where poster will be saved

str

required

File format: ‘png’, ‘svg’, or ‘pdf’

int

default:"12"

Poster width in inches (maximum: 20)

int

default:"16"

Poster height in inches (maximum: 20)

str

Optional override for country text displayed on poster

str

Optional override for city name (reserved for future use)

str

Custom display name for city (supports internationalization)

str

Custom display name for country (supports internationalization)

dict

Custom font dictionary with ‘bold’, ‘regular’, ‘light’ keys mapping to font file paths. If None, uses default FONTS.

RuntimeError

If street network data cannot be retrieved from OpenStreetMap

Display Name Priority

The function uses the following priority for display names:

display_city / display_country (highest priority)
name_label / country_label
city / country (fallback)

Text Formatting

The function automatically handles different scripts:

Latin scripts: Applies uppercase and letter spacing (e.g., “P A R I S”)
Non-Latin scripts (CJK, Arabic, Thai, etc.): Preserves case structure without spacing

get_coordinates()

Fetch coordinates for a given city and country using geopy geocoding service.

get_coordinates(city, country)

Includes automatic caching and rate limiting to be respectful to the geocoding service.

str

required

City name to geocode

str

required

Country name to geocode

tuple

(latitude, longitude) tuple of floats

ValueError

If coordinates cannot be found or geocoding fails

Caching Behavior

Coordinates are automatically cached using the key format: coords_{city.lower()}_{country.lower()} If cached coordinates exist, they are returned immediately without making a network request.

load_theme()

Load a theme configuration from JSON file in the themes directory.

load_theme(theme_name="terracotta")

str

default:"terracotta"

Name of the theme file (without .json extension)

dict

Theme dictionary containing all color configuration fields. See Theme Schema for complete field documentation.

Fallback Behavior

If the specified theme file is not found, the function:

Prints a warning message
Returns the embedded terracotta theme as fallback

Theme Directory

Theme files must be located in: themes/{theme_name}.json

get_available_themes()

Scan the themes directory and return a list of available theme names.

get_available_themes()

list[str]

List of theme names (without .json extension), sorted alphabetically

Behavior

Creates the themes directory if it doesn’t exist
Returns empty list if no themes are found
Only includes files with .json extension

fetch_graph()

Fetch street network graph from OpenStreetMap using OSMnx.

fetch_graph(point, dist)

Uses caching to avoid redundant downloads. Fetches all network types within the specified distance from the center point.

tuple

required

(latitude, longitude) tuple for center point

int

required

Distance in meters from center point

MultiDiGraph | None

NetworkX MultiDiGraph of street network, or None if fetch fails

Caching

Graphs are cached using the key format: graph_{lat}_{lon}_{dist}

Rate Limiting

Includes automatic 0.5 second delay between requests to respect OpenStreetMap usage policies.

fetch_features()

Fetch geographic features (water, parks, etc.) from OpenStreetMap.

fetch_features(point, dist, tags, name)

Uses caching to avoid redundant downloads. Fetches features matching the specified OSM tags within distance from center point.

tuple

required

(latitude, longitude) tuple for center point

int

required

Distance in meters from center point

dict

required

Dictionary of OSM tags to filter features (e.g., {"natural": ["water", "bay"], "waterway": "riverbank"})

str

required

Name for this feature type (used for caching and logging)

GeoDataFrame | None

GeoPandas GeoDataFrame of features, or None if fetch fails

Example Tags

tags = {
    "natural": ["water", "bay", "strait"],
    "waterway": "riverbank"
}

tags = {
    "leisure": "park",
    "landuse": "grass"
}

Rate Limiting

Includes automatic 0.3 second delay between requests.

Cache Functions

cache_get()

Retrieve a cached object by key.

cache_get(key)

str

required

Cache key identifier

Any | None

Cached object if found, None otherwise

CacheError

If cache read operation fails

cache_set()

Store an object in the cache.

cache_set(key, value)

str

required

Cache key identifier

Any

required

Object to cache (must be picklable)

CacheError

If cache write operation fails

Cache Directory

Cache files are stored in the directory specified by the CACHE_DIR environment variable, defaulting to ./cache/

Utility Functions

generate_output_filename()

Generate unique output filename with city, theme, and datetime.

generate_output_filename(city, theme_name, output_format)

str

required

City name

str

required

Theme name

str

required

File extension (png, svg, pdf)

str

Full path to output file: posters/{city_slug}_{theme_name}_{timestamp}.{ext}

is_latin_script()

Check if text is primarily Latin script.

is_latin_script(text)

Used to determine if letter-spacing should be applied to city names on the poster.

str

required

Text to analyze

bool

True if text is primarily Latin script (>80% of alphabetic characters), False otherwise

Latin Unicode Ranges

Basic Latin: U+0000 to U+007F
Latin-1 Supplement: U+0080 to U+00FF
Latin Extended-A: U+0100 to U+017F
Latin Extended-B: U+0180 to U+024F

API

Contributing

create_poster()

Display Name Priority

Text Formatting

get_coordinates()

Caching Behavior

load_theme()

Fallback Behavior

Theme Directory

get_available_themes()

Behavior

fetch_graph()

Caching

Rate Limiting

fetch_features()

Example Tags

Rate Limiting

Cache Functions

cache_get()

cache_set()

Cache Directory

Utility Functions

generate_output_filename()

is_latin_script()

Latin Unicode Ranges

​create_poster()

​Display Name Priority

​Text Formatting

​get_coordinates()

​Caching Behavior

​load_theme()

​Fallback Behavior

​Theme Directory

​get_available_themes()

​Behavior

​fetch_graph()

​Caching

​Rate Limiting

​fetch_features()

​Example Tags

​Rate Limiting

​Cache Functions

​cache_get()

​cache_set()

​Cache Directory

​Utility Functions

​generate_output_filename()

​is_latin_script()

​Latin Unicode Ranges

create_poster()

Display Name Priority

Text Formatting

get_coordinates()

Caching Behavior

load_theme()

Fallback Behavior

Theme Directory

get_available_themes()

Behavior

fetch_graph()

Caching

Rate Limiting

fetch_features()

Example Tags

Rate Limiting

Cache Functions

cache_get()

cache_set()

Cache Directory

Utility Functions

generate_output_filename()

is_latin_script()

Latin Unicode Ranges