Various helper classes for accessing the free geocoding services at
Switch branches/tags
Nothing to show
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.



ILGeoNames provides Objective C wrapper classes for accessing the free geocoding services at from iOS.

Unlike the geocoding services provided by Google which have various restricting license terms, GeoNames allows you to use their data for practically any purpose as long as you give proper credit.

Setting up the sample application

In order to be able to use this sample application you need to perform a few additional steps first:

  • Sign up for a free account a
  • Enter your new geonames account information in SampleAppDelegate.m
  • Download JSONKit
  • Download OCMock

Each of these steps are detailed in more details below.

Sign up for a free GeoNames account

If you do not already have an account with GeoNames, you first need to go to and sign-up for a free account. Shortly after you should get an confirmation email with information on how to activate your account.

Once you have activated your account you also need to enable it to use the free web service. This is done from your GeoNames account page by simply clicking a link. Once enabled, your account is ready to be used with the various geocoding services.

Setting up account information

Open the SampleApp.xcodeproj file and locate the file named SampleAppDelegate.m Locate the following line near the top of the file and replace the account information with your own.

static NSString *kGeoNamesAccountName = @"ilgeonamessample";

Download JSONKit

The ILGeoNames classes makes use of JSONKit by John Engelhart. In order to be able to build the sample project - and your own for that matter - you need to download a copy of the JSONKit code from GitHub

Once downloaded, place the JSONKit folder next to the SampleApp folder. Alternatively, if you already have your own fork of JSONKit, just point the sample project to your local repository.

Download OCMock

The UnitTest code makes use of OCMock from Mulle Kybernetik. In order to be able to run the unit tests you will need to download the latest version of OCMock from Mulle Kybernetik

Once downloaded, unpack it and place it next to the SampleApp folder. You may need to remove the version from the folder name so it s just called OCMock.

You should now be ready to compile and run the sample application. The application shows examples on how to use the following classes:

  • ILGeoNamesLookup, the basic wrapper for accessing
  • ILGeoNamesSearchController, a search controller for online search of named locations

For more information about ILGeoNames and how to use it, please visit

Building Xcode Documentation

ILGeoNames is documented in the header files using the appledoc syntax. The SampleApp contains a target called "Documentation" which will build the documentation and install it for use inside Xcode as a searchable and browsable docset. In order to be able to build it you will need to install appledoc on your own computer. You can get appledoc from GitHub. For more information about how to setup and build the documentation you can read this short tutorial.

Feel free to add enhanchements, bug fixes, changes and provide them back to the community!


Claus Broch