Command Line Interface (CLI) Geocoding Tutorial

Topics covered in this tutorial

• Who this tool is for
• 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.

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.

Installing the OpenCage Command Line Interface (CLI) tool

Compatible with Python version 3.8 and newer.

pip install 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

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 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
Philipsbornstr 2, 30165 Hannover, 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.

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.

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 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:

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.