Skip to main content
After choosing a provider, you decide which parts of its response appear in your file and folder names, and in what order. Each provider returns a different set of address components — administrative levels, named properties, or typed fields — and you pick a subset that forms the location portion of the name. photo-cli joins your selections with the address separator (default: -) to produce strings like United Kingdom-Ascot-Sunninghill and Ascot.

​
Understanding address components

Every reverse geocode provider returns a response with multiple geographic fields. The fields available depend on the provider and on the location of the photo. Before building your configuration, inspect the raw response for a representative photo to understand what each provider returns for your specific locations. Run the following command to see all available properties for a photo with your chosen provider:
Once you know the field names or level numbers, pass them as your selection arguments.

​
OpenStreetMap Foundation and LocationIq

Both OpenStreetMap Foundation and LocationIq return OpenStreetMap-style named properties. Pass the property names you want — separated by spaces — to --openstreetmap-properties (-r). The order you list them is the order they appear in the address. Common property names: Example — inspect the full response for a photo:
Sample output for a photo taken in Ankara, Turkey:
Select specific properties and verify the result:
Output:

​
BigDataCloud

BigDataCloud represents its address hierarchy as numbered administrative levels. Pass the level integers you want to --bigdatacloud-levels (-u), separated by spaces. Example — inspect the full response:
Sample output:
Select levels 2, 4, and 6 and verify:
Output:
Admin level numbers vary by country and region. Always run photo-cli address on photos from the locations you photograph before finalising your level selection.

​
Google Maps

Google Maps returns named address types. Pass the type strings you want to --googlemaps-types (-m), separated by spaces. Example — inspect the full response:
Sample output:
Select specific types and verify:
Output:

​
Full address building example

The following example shows the complete flow from raw coordinates to a final address string using OpenStreetMap Foundation:
  • Coordinate: 51.4248, -0.6736
  • Provider response: Country: United Kingdom, City: Ascot, Suburb: Sunninghill and Ascot
  • Selection: --openstreetmap-properties Country City Suburb
  • Result: United Kingdom-Ascot-Sunninghill and Ascot
This string becomes the location portion of the file name, combined with date information according to your chosen naming style — for example: 2024.06.15_10.30.00-United Kingdom-Ascot-Sunninghill and Ascot.jpg.

​
Caching

photo-cli caches reverse geocode responses per coordinate to avoid making duplicate API calls. Coordinates are rounded to four decimal places before the request is sent, so photos taken within a few metres of each other share a single cached response. If you need more precise per-photo results, increase the precision with:

​
Changing the address separator

By default, photo-cli joins your selected address components with -. To use a different separator — for example _ — save it in settings:
After this change, United Kingdom-Ascot-Sunninghill and Ascot becomes United Kingdom_Ascot_Sunninghill and Ascot.