Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/originalankur/maptoposter/llms.txt

Use this file to discover all available pages before exploring further.

​
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.
​
city
str
required
City name for display on poster
​
country
str
required
Country name for display on poster
​
point
tuple
required
(latitude, longitude) tuple for map center
​
dist
int
required
Map radius in meters (e.g., 4000-6000m for small cities, 15000-20000m for large metros)
​
output_file
str
required
Path where poster will be saved
​
output_format
str
required
File format: ‘png’, ‘svg’, or ‘pdf’
​
width
int
default:"12"
Poster width in inches (maximum: 20)
​
height
int
default:"16"
Poster height in inches (maximum: 20)
​
country_label
str
Optional override for country text displayed on poster
​
name_label
str
Optional override for city name (reserved for future use)
​
display_city
str
Custom display name for city (supports internationalization)
​
display_country
str
Custom display name for country (supports internationalization)
​
fonts
dict
Custom font dictionary with ‘bold’, ‘regular’, ‘light’ keys mapping to font file paths. If None, uses default FONTS.
​
raises
RuntimeError
If street network data cannot be retrieved from OpenStreetMap

​
Display Name Priority

The function uses the following priority for display names:
  1. display_city / display_country (highest priority)
  2. name_label / country_label
  3. 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.
​
city
str
required
City name to geocode
​
country
str
required
Country name to geocode
​
return
tuple
(latitude, longitude) tuple of floats
​
raises
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")
​
theme_name
str
default:"terracotta"
Name of the theme file (without .json extension)
​
return
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:
  1. Prints a warning message
  2. 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()
​
return
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.
​
point
tuple
required
(latitude, longitude) tuple for center point
​
dist
int
required
Distance in meters from center point
​
return
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.
​
point
tuple
required
(latitude, longitude) tuple for center point
​
dist
int
required
Distance in meters from center point
​
tags
dict
required
Dictionary of OSM tags to filter features (e.g., {"natural": ["water", "bay"], "waterway": "riverbank"})
​
name
str
required
Name for this feature type (used for caching and logging)
​
return
GeoDataFrame | None
GeoPandas GeoDataFrame of features, or None if fetch fails

​
Example Tags

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

​
Rate Limiting

Includes automatic 0.3 second delay between requests.

​
Cache Functions

​
cache_get()

Retrieve a cached object by key. 
cache_get(key)
​
key
str
required
Cache key identifier
​
return
Any | None
Cached object if found, None otherwise
​
raises
CacheError
If cache read operation fails

​
cache_set()

Store an object in the cache. 
cache_set(key, value)
​
key
str
required
Cache key identifier
​
value
Any
required
Object to cache (must be picklable)
​
raises
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)
​
city
str
required
City name
​
theme_name
str
required
Theme name
​
output_format
str
required
File extension (png, svg, pdf)
​
return
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.
​
text
str
required
Text to analyze
​
return
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

Build docs developers (and LLMs) love

Get started for freeTalk to us