Using

There are three main ways to use Fetegeo:

By sending requests to the Fetegeo server fetegeos.
By using the command-line client fetegeoc to send requests to a Fetegeo server.
Embedding the Fetegeo library within a client.

`fetegeoc`

At it's simplest fetegeoc can be used to perform free-text queries which will return matches that look like the following:

$ fetegeoc geo London
Match #1
  ID: 719913
  Name: London
  Latitude: 51.508415
  Longitude: -0.125533
  Country ID: 233
  Parent ID: 1262
  Population: 7421209
  PP: London, United Kingdom
  Dangling text:
$

Dangling text

One of the possibilities that free text geocoding offers is of typing a domain specific query followed by geocode text. For example users might like to search for cafe in pimlico. By default, Fetegeo matches the complete input, and fails if it is unable to do so. Fetegeo can be told to allow dangling text, that is text which Fetegeo can't match as being a place name but which a subsequent program may then be able to process and make sense of. To allow dangling text with fetegeoc add the -d option:

$ fetegeoc -d geo cafe in Pimlico
Match #1
  ID: 742075
  Name: Pimlico
  Latitude: 51.488973
  Longitude: -0.136986
  Country ID: 233
  Parent ID: 1262
  Population: 0
  PP: Pimlico, United Kingdom
  Dangling text: cafe in
$

Biasing the search

Typically users prefer that they are shown matches in their own country. Using fetegeoc's -c <iso2 country name> switch allows searches to be restricted to a particular country. So instead of:

$ fetegeoc geo Penrith
Match #1
  ID: 716589
  Name: Penrith
  Latitude: 54.65
  Longitude: -2.733333
  Country ID: 233
  Parent ID: 11255
  Population: 14793
  PP: Penrith, Cumbria, United Kingdom
  Dangling text:

Match #2
  ID: 2517801
  Name: Penrith
  Latitude: -43.848333
  Longitude: 171.600105
  Country ID: 158
  Parent ID: 2941
  Population: 0
  PP: Penrith, Canterbury, New Zealand
  Dangling text:
$

one gets:

$ fetegeoc -c nz geo Penrith
Match #1
  ID: 2517801
  Name: Penrith
  Latitude: -43.848333
  Longitude: 171.600105
  Country ID: 158
  Parent ID: 2941
  Population: 0
  PP: Penrith, Canterbury, New Zealand
  Dangling text:
$

If instead you wish to see all matches, but with matches in a particular country highlighted then use fetegeoc's -a switch as well:

$ fetegeoc -a -c nz geo Penrith
Match #1
  ID: 2517801
  Name: Penrith
  Latitude: -43.848333
  Longitude: 171.600105
  Country ID: 158
  Parent ID: 2941
  Population: 0
  PP: Penrith, Canterbury, New Zealand
  Dangling text:

Match #2
  ID: 716589
  Name: Penrith
  Latitude: 54.65
  Longitude: -2.733333
  Country ID: 233
  Parent ID: 11255
  Population: 14793
  PP: Penrith, Cumbria, United Kingdom
  Dangling text:
$

Localization

Fetegeo is language-agnostic when searching, but returns results in preferred language(s) when possible. The default language is English, but other languages can be specified via fetegeoc's -l <iso639_1 language code>:

$ fetegeoc -l pt geo London
Match #1
  ID: 719922
  Name: Londres
  Latitude: 51.5084152564
  Longitude: -0.125532746315
  Country ID: 233
  Parent ID: 1262
  Population: 7421209
  PP: Londres, Reino Unido
  Dangling text:

Multiple -l options can be specified; the languages are treated in descending order of preference.

`fetegeos`

fetegeos is the Fetegeo server. It is a multi-threaded server that responds to XML requests. One advantage of using fetegeos is that it adaptively caches data, speeding up related searches.