# Command Line Interface (CLI) Geocoding Tutorial

## OpenCage Geocoding API Command Line Interface (CLI) Tutorial

Tutorial for using the OpenCage Geocoding API in Command Line Interface (CLI) - An API for reverse and forward geocoding using open geo data

We have developed a command line tool specifically for helping with geocoding large CSV files of addresses or coordinates.

### Topics covered in this tutorial

- Who this tool is for
- Agent Skill
- Video tutorial
- Installing the tool
- Required arguments
- Help
- Reverse geocoding
- Forward geocoding
- Examples
- Testing and dealing with broken data

### Who this tool is for

The OpenCage command line interface (CLI) tool is designed for developers, data analysts, or GIS professionals who need to process files from the command line. It's best suited for people already familiar with the command line and with the concepts of geocoding.

### Agent Skill / Working with AI

Are you developing with AI?

We offer [an Agent Skill](https://github.com/OpenCageData/opencage-skills/) that includes [a reference file specifically about accessing our API via the command line](https://github.com/OpenCageData/opencage-skills/blob/master/skills/opencagegeocoding-api/references/commandline.md).

### Video Tutorial

If you prefer video, over on YouTube we have a 10 minute tutorial video explaining the general concepts of geocoding and showing [how to use the command line tool to geocoding CSV files](https://www.youtube.com/watch?v=yOY-owe0rqE).

### Installing the OpenCage Command Line Interface (CLI) tool

Compatible with Python version 3.8 and newer.

    pip install opencage

[on GitHub](https://github.com/opencagedata/python-opencage-geocoder) [on PyPi](https://pypi.python.org/pypi/opencage/)

### Required arguments

When using the OpenCage CLI, you'll need to provide the following required arguments:

- `command` "forward" or "reverse"
- `--api-key` Your OpenCage Geocoding API key
- `--input` The input file containing addresses or coordinates
- `--output` The output file where results will be saved

### Help

To get help on using the OpenCage CLI, use the `--help` option.

    opencage forward --help
    
    opencage reverse --help

[](https://assets.opencagedata.com/assets/tutorials/cli-b65521f61dbc1549db9a4421d546021a6d11c8cadd6aff8d2e0f8c5b29806dd2.gif) ! [Commandline example](https://assets.opencagedata.com/assets/tutorials/cli-b65521f61dbc1549db9a4421d546021a6d11c8cadd6aff8d2e0f8c5b29806dd2.gif)

### Convert coordinates to location (reverse geocoding)

You have a text file called `coordinates.csv` containing decimal coordinates (in latitude, longitude format). We prepared a couple of [example files](https://opencagedata.com/tools/address-lists) for testing.

    44.8303087,-0.5761911
    2.345,10.2423
    9.781652,124.391118
    65.21345,50.234556

Geocode the coordinates and save the output in a file called `addresses.csv`

    opencage reverse --api-key YOUR-API-KEY --input coordinates.csv --output addresses.csv

### Lookup coordinates from address (forward geocoding)

You have a text file called `addresses.csv` containing places:

    Madrid, Spain
    Milan, Italy
    Berlin, Germany
    München, Deutschland
    Pappelallee 78/79, 10437 Berlin, Germany

Geocode the addresses to latitude, longitude coordinates and write the output to a file `coordinates.csv`

    opencage forward --api-key YOUR-API-KEY --input addresses.csv --output coordinates.csv

### Examples

Here we show some of the various optional flags the `opencage` command line tool makes available. For a full list use [the --help flag](#help).

#### Optional API Parameters

Set optional geocoding API parameters using the `--optional-api-params` option.

Here's an example where we set `language ` and ` countrycode`.

    opencage forward --api-key YOUR-API-KEY --input paris.csv --output paris-usa.out.csv --optional-api-params 'countrycode=us,language=fr'

See the geocoding API documentation for [the full list of optional parameters](https://opencagedata.com/api#optional-params).

#### Running many parallel API requests using workers

To speed up processing of large datasets, you can use multiple parallel workers with the `--workers` option. Maximum value is 20. This option only works for paying customers, not free trial users.

    opencage reverse --api-key YOUR-API-KEY --input coordinates.csv --output results.csv --workers 4

Before you start geocoding at high volume, please read our [guide to geocoding large datasets](https://opencagedata.com/guides/how-to-geocode-large-datasets) where we explain various strategies and points to consider.

#### Headers

Use the `--headers` option to treat the first row of your input file as headers. For example you don't want to geocode the 'City,Country' line. The output will also have headers.

    City,Country
    Madrid,Spain
    Milan,Italy
    Berlin,Germany

    opencage forward --api-key YOUR-API-KEY --input addresses.csv --output results.csv --headers

#### Input Columns

For a reverse search you tell the tool in which columns where the latitude and longitude are located. With

    1,44.8303087,-0.5761911,medium
    2,2.345,10.2423,high
    3,9.781652,124.391118,low

you should set `--input-columns 2,3` (The first column is 1, not 0).

For a forward search you want to tell the tool which columns contain the combined full address. With

    1,Germany,Hauptstrasse 123,12345,Frankfurt,medium

you should set `--input-columns 3,4,5,1` and the tool will geocode "Hauptstrasse 123, 12345, Frankfurt, Germany".

#### Add Columns

By default these columns will be added to the output:

| lat |
| lng |
| \_type |
| \_category |
| country\_code |
| country |
| state |
| county |
| \_normalized\_city |
| postcode |
| road |
| house\_number |
| confidence |
| formatted |

Specify a comma separated list of output columns with the `--add-columns` option:

    opencage reverse --api-key YOUR-API-KEY --input coordinates.csv --output results.csv --add-columns formatted,country,postcode

### Testing and dealing with broken data

- With `--dry-run` the input file is read but no geocoding will be done. It will print warnings for any unreadable rows, for example missing columns, empty rows or invalid coordinates.
- Setting `--limit 50` will only process the first 50 lines of the input file.
- With `--verbose` for each API request the full URL and API response is printed. That is useful for checking which data fields might be useful to you.

### Further Reading

- [OpenCage geocoding API Reference](https://opencagedata.com/api)
- [Comparing geocoding services](https://opencagedata.com/guides/how-to-compare-and-test-geocoding-services)
- [Cleaning / formatting your forward geocoding query](https://opencagedata.com/guides/how-to-format-your-geocoding-query)
- [Geocoding more quickly](https://opencagedata.com/guides/how-to-geocode-more-quickly)
- [Geocoding large datasets](https://opencagedata.com/guides/how-to-geocode-large-datasets)
- [Geocoding and preserving privacy](https://opencagedata.com/guides/how-to-preserve-privacy-by-showing-only-an-imprecise-location)
- [Sample address and coordinate lists for testing](https://opencagedata.com/tools/address-lists)