Skip to main content

Documentation Index

Fetch the complete documentation index at: https://photocli.com/llms.txt

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

Reverse geocoding converts the GPS coordinates embedded in your photos into human-readable location names — things like country, city, or neighborhood — that photo-cli can include in your file and folder names. When you run copy or archive with a reverse geocode provider configured, photo-cli reads the latitude and longitude from each photo’s EXIF data, sends them to the provider, receives back a structured address response, and uses the components you select to build a location string like France-Paris-Montmartre.

​
How it works

photo-cli follows this sequence for every photo that has GPS coordinates:
1

Read GPS coordinates

photo-cli extracts the latitude and longitude stored in the photo’s EXIF metadata.
2

Send to reverse geocode provider

The coordinates are sent to your chosen third-party provider — BigDataCloud, OpenStreetMap, Google Maps, or LocationIq.
3

Receive address components

The provider returns a response containing administrative levels or named properties such as country, city, and suburb.
4

Select and build the address string

You specify which components to include. photo-cli joins them with the address separator (default: -) to produce the location portion of your file or folder name.
The result appears in file names like 2024.03.15-France-Paris-Montmartre.jpg or in folder names like France-Paris/ depending on the naming and grouping strategy you choose.

​
When to use reverse geocoding

Use reverse geocoding when you want file names or folder names to include meaningful location information. For example:
  • 2024.03.15-United Kingdom-Ascot-Sunninghill and Ascot.jpg
  • Turkey-Ankara-Çankaya/
  • 2024.03.15_14.22.01-France-Paris.jpg
If you only care about date-based organization and do not need place names in your output, you can skip reverse geocoding entirely. Simply omit --reverse-geocode (-e) from your command and photo-cli will use date information alone.
Reverse geocode responses are cached per coordinate (rounded to four decimal places) to avoid redundant API calls. If multiple photos were taken at the same location, the provider is only called once.
Some providers enforce rate limits. photo-cli respects these automatically — for example, OpenStreetMap Foundation is limited to one request per second. LocationIq free-tier users are subject to the same limit unless they pass --has-paid-license.

​
Next steps

Choose a provider

Compare BigDataCloud, OpenStreetMap, Google Maps, and LocationIq to find the right fit.

Set up your API key

Learn how to supply your API key as an argument, environment variable, or saved setting.

Build your address

Select address components and configure the separator to control what appears in file names.

Preview with address command

Use photo-cli address to inspect a provider’s response for a single photo before running copy or archive.