Configuration¶

For manual runs, coordinate testing, and reset tools, see Using the App.

Database settings¶

Database values are environment-backed and shown as read-only in the UI.

The app reads:

• DB_HOST
• DB_PORT
• DB_USERNAME
• DB_PASSWORD
• DB_DATABASE_NAME

These values are required because the app reads and updates immich data directly.

Processing settings¶

The Settings page lets you control:

• whether processing runs automatically
• when it runs, using simple presets or a custom cron expression
• batch size, delay, and parallelism
• whether airport infrastructure can override the city name
• whether GADM administrative areas are enabled as an optional source
• whether GADM should be preferred over cached Overture divisions
• whether split-territory GADM fallback families should be tried
• whether every asset is written to the log

Most users should stay on the preset schedule options. Manual runs from the dashboard still work even when automatic scheduling is disabled.

GADM administrative areas¶

When enabled, GADM adds another country-level administrative boundary source for state and city matching.

Recommended starting point:

• turn Enable GADM administrative areas on
• leave Prefer GADM administrative results off at first
• use Lookup to compare results before making GADM the primary admin source

What it can help with:

• countries where Overture admin divisions are sparse or pick the wrong city-like name
• places where a more traditional admin-boundary dataset gives better municipality or state names

What it does not fix by itself:

• wrong bundled country detection
• airport names winning when airport matching is still enabled
• missing places that are not present in either source

Split-territory fallback families¶

The optional GADM territory fallback setting lets the app try a small related country family when a sovereign or mainland code may be too coarse.

Examples include:

• Denmark, Greenland, and the Faroe Islands
• United Kingdom, Jersey, Guernsey, and the Isle of Man

This is a targeted fallback, not a global scan of every possible territory.

City Resolver¶

The City Resolver page lets you adjust how the app picks a city name when Overture returns several possible matches.

It gives you:

• bundled default rules that ship with the app
• an optional global override
• country-specific overrides
• a searchable country picker
• simple up/down controls to change the order of preferred place types from the official Overture list
• a choice between:
• prefer the tighter match
• prefer the broader match

This keeps the main Settings page simple while still giving you a way to fix countries where the default city result is not what you want.

What it actually changes¶

The City Resolver only affects the city value.

It is useful when the app finds the right general area, but chooses the wrong name for your taste. For example:

• it picks a district instead of the wider city
• it picks a very small local area instead of the municipality
• it picks something broader than you want

What it does not change¶

The City Resolver does not download better data or invent missing places.

It will not help if:

• the place you want is not in the Lookup results at all
• the airport name is winning and airport matching is still turned on
• the country match is wrong

So before changing anything, use Lookup first and make sure the place you want is actually in the returned data.

Recommended workflow¶

1. Open the Lookup page and test a coordinate that gave you a bad city result.
2. Look at Resolved City, Raw Best Area, and the candidate list.
3. If the place you want is present, decide what to change:
4. if the wrong kind of place won, change the preferred order
5. if two similar places are competing, try broader or tighter matching
6. if an airport name is winning, turn off airport matching first
7. Add a country override only after you know the data supports the result you want.
8. Run Lookup again and confirm the final output before processing your library.

About admin_level¶

Lookup shows admin_level because it can sometimes help explain why a result was chosen, but it is not a setting you edit directly.

That is because:

• many results do not have a useful admin_level
• the place type is usually more important than the number
• admin_level alone does not solve every case

So the controls on the City Resolver page stay simple:

• preferred place type order
• broader or tighter matching

Bundled defaults vs your overrides¶

The app ships with built-in default rules. Your own settings sit on top of them:

• bundled global default
• bundled country-specific default, if present
• your optional global override
• your optional country override

That means you only need to change the countries you care about.

Want to improve the bundled defaults for everyone?¶

If you find a country setting that clearly works better, you can open a pull request.

The bundled defaults currently live in:

• src/ImmichReverseGeo.Web/bundled-data/defaults/city-resolver-profiles.json

A good pull request should include:

• the country ISO3 code
• one or more example coordinates
• the old result
• the new expected result
• a short explanation of why the new default is better
• Lookup evidence showing that the desired place is really in the returned data

See the contributor notes in CONTRIBUTING.md.

Database connection details¶

The database section in Settings is read-only and mainly there as a sanity check.

• values are taken from the running process environment
• they are not stored in settings.json

Data layout¶

Runtime data goes under /data.

Config goes under /config in production.

Operational notes¶