The AFD Names & Numbers for Android API is easy to use and quick to implement in any Android application, while balancing that with providing full flexibility. A JAR file (afdnn.jar) alongside our native library (libafdnn.so) provides access to Names & Numbers functionality once added to your project.
For rapid development and for a quick start, take a look at our sample program to see how Names & Numbers is integrated. When you run that on Android you will need to copy your licence file to your chosen data folder on the device (unless using evaluation data). The data files (names.afd, namesi.afd, etc.) will also need to be present either along with your application or on external storage. If file transfer is more difficult, you can simplify this by transfering the licence file using the SaveLicense method and obtain the latest data files automatically using the update functionality.
To integrate Names & Numbers into your own Project simply add the afdnn.jar file to your project libs folder and the libafdnn.so to libs\armeabi. Then create an instance of the afd.nn.Engine class to access AFD Names & Numbers functionality.
On creating an instance of the afd.nn.Engine class you should pass the path to access the product data files from, for example for application private storage:
Engine nnEngine = new afd.nn.Engine(getFilesDir());
Or for an example of an external path:
Engine nnEngine = new afd.nn.Engine(“/mnt/sdcard/nndata/”);
For non-evaluation purposes we recommend using the automatic update functionality to obtain the latest data files and using the saveLicense method to save the licence from a Base64 encoded string.
A sample application demonstrating AFD Names & Numbers functionality is provided with the SDK.
To use this load the project in Eclipse and then click Run and follow any prompts to start the application on your device.
The path to the data folder is set in the top of the common.java and is displayed on the FastFind screen of the sample application. You may need to change this to point to an appropriate location for your target device.
For Evaluation data, copy that data to a folder on the device, or include it in your apk and ensure you have set the data path correctly as above.
For Full data, either transfer the nn.lic licence file to the device or use the saveLicense method to generate the file from a Base64 string that AFD will have supplied. Then use the checkForUpdates function to obtain the latest data.
The addressGetFirst and addressGetNext methods enable address records to quickly be located.
This is typically done as follows:
See the appropriate function and property references for full details of these methods and properties.
An example lookup is as follows:
// Create an instance of the afd.nn.Engine class
Engine nnEngine = new afd.nn.Engine();
// Set the search criteria
nnEngine.clear();
nnEngine.setSearchLookup("B6 4AA");
// Do the lookup
int retVal = nnEngine.addressGetFirst(0);
// Deal with any error
if (retVal < 0) {
AlertDialog.Builder dlgAlert = new AlertDialog.Builder(this);
dlgAlert.setTitle("Error");
dlgAlert.setMessage(nnEngine.errorText(retVal));
dlgAlert.create().show();
return;
}
// Retrieve the results
while (retVal >= 0) {
if (retVal != nnEngine.AFD_RECORD_BREAK) {
String listItem = nnEngine.getAddressList();
// do something with this data
}
retVal = nnEngine.addressGetNext();
The jumpToRecord method enables records to be quickly retrieved again, (from a list displayed to the user, for example) using its record key.
This is typically done as follows:
See the appropriate function and property references for full details of this method and properties.
An example retrieve is as follows, were recordKey is the result of calling getRecordKey for the record originally retrieved:
// Create an instance of the afd.nn.Engine class
Engine nnEngine = new afd.nn.Engine();
// Do the lookup
int retVal = nnEngine.jumpToRecord(recordKey);
// Deal with any error
if (retVal < 0) {
AlertDialog.Builder dlgAlert = new AlertDialog.Builder(this);
dlgAlert.setTitle("Error");
dlgAlert.setMessage(nnEngine.errorText(retVal));
dlgAlert.create().show();
return;
}
// Retrieve the result
String organisation = nnEngine.getOrganisation();
String property = nnEngine.getProperty();
String street = nnEngine.getStreet();
String locality = nnEngine.getLocality();
String town = nnEngine.getTown();
String postcode = nnEngine.getPostcode();
// do something with this data
To use full data with AFD Names & Numbers, a License will need to be purchased from AFD. This is provided in two forms, a file nn.lic and a Base64 encoded version to make entry or transfer easier.
Either save the nn.lic file in your data folder, or use the saveLicense method to pass the supplied base64 encoded text string to apply the license.
The process to do this is typically as follows:
An example of doing this is as follows:
int applied = nnEngine.saveLicense(licenseString);
if (applied == 1) {
// success
}
else {
// license string not valid
}
To update Names & Numbers data, the data files (names.afd, namesi.afd, etc.) need to be replaced in your data folder with the latest versions available from our server.
This can be done automatically using instance functions of the afd.nn.Engine class provided for updating.
The process to do this is typically as follows:
An example of doing this is as follows:
int needUpdate = afd.nn.Engine.checkForUpdate();
if (needUpdate == 1) {
int startedDownload = afd.nn.Engine.downloadUpdate();
if (startedDownload == 1) {
while (afd.nn.Engine.isDownloadComplete() == 0) {
// wait for download to complete – can carry on with other
tasks
}
int updateApplied = afd.nn.Engine.applyUpdate();
}
Clears the search properties ready to start a new search public void clear();
This function takes no parameters and returns no value.
Starts a lookup or search and returns the first record
Prior to calling this function, call Clear and set the appropriate search parameters to specify the fields you wish to search for (e.g. setSearchLookup).
public int addressGetFirst(int flags)
flags is an integer and specifies options for the search. These are as follows:
The function returns one of the following values:
If AFD_SUCCESS is returned you can then call any of the properties to obtain the fields for the returned record, e.g. getAddressList. If AFD_SUCCESS or AFD_RECORD_BREAK is returned you should call addressGetNext to retrieve each subsequent record until AFD_END_OF_SEARCH is returned.
Continues a lookup or search, returning the next matching record
public int addressGetNext()
This function takes no parameters.
The function returns one of the following values:
If AFD_SUCCESS is returned you can then call any of the properties to obtain the fields for the returned record, e.g. getAddressList.
If AFD_SUCCESS or AFD_RECORD_BREAK is returned you should continue to call AddressGetNext to retrieve each subsequent record until AFD_END_OF_SEARCH is returned.
Returns data for the record key supplied
public int jumpToRecord(String recordKey)
The recordKey parameter is the key of the record to be retrieved. This would have been returned by using the getRecordKey method following a previous call to AddressGetFirst or AddressGetNext. Note this key should not be stored as it is not maintained across data updates; it is designed for reretrievinga record following a list being provided to the user.
The function returns one of the following values:
If AFD_SUCCESS is returned, any of the properties can then be called to obtain the fields for the returned record, e.g. getStreet.
Used to retrieve text to display a friendly error message to go with an error code returned from the search or validation functions (return value less than zero).
public String errorText(int errorCode)
errorCode is an int and should be set to the return value from a previous function call.
On return a description for the error is returned which can be stored or displayed for the user.
Used to save a license file on the device from a Base64 encoded string representation.
public int saveLicense(string base64License)
Base64License is the string containing the base64 encoded license data.
Returns:
Used to check if an update to the Names & Numbers data files is available.
public int checkForUpdate()
Returns:
Used to start downloading a data update.
public int downloadUpdate()
Returns:
When the function returns data continues to download in the background so your application can continue running. Poll with IsDownloadComplete periodically to determine when the download has finished.
Used to indicate when a data download has completed downloading public int isDownloadComplete()
Returns:
Used to update data files following a successful download and loads the new dataset.
public int applyUpdate()
Returns:
Note that you mustn’t call the Names & Numbers functions while this call is completing as old data will be unloaded, the new data unpacked and then loaded during this call. Hence this call does block the thread it is called on which is assumed to be the one you carry out Names & Numbers calls on.
Getter and setter methods are provided for the Names & Numbers fields.
These are as follows:
| Field Name | Description |
|---|---|
| Searchable Only Fields (no get method) | |
| SearchLookup | Specify fast-find string to look for, e.g. a postcode or street, town. No other search fields should be set when this is used. |
| Miles | Set distance in miles to search around (for radial searches) |
| Km | Set distance in kilometres to search around |
| Result Only Fields (no set method) | |
| AddressList | Returns a formatted line for list insertion containing elements of the Address record. Useful when displaying a list of results for the user to choose from. |
| RecordKey | Returns a record key to use for subsequent retrieval of the record with AddressRetrieve. Note this should not be stored as it does not persist across data updates. |
| Name | Returns a formatted Name with title, e.g. “Mr John J Smith” |
| Formatted Address Fields | |
| Postcode | Returns the Postcode |
| PostcodeFrom | Returns the original postcode if the postcode searched for has been changed (re-coded). |
| Organisation | Returns the Organisation Name |
| Property | Returns the Building Name |
| Street | Returns the House Number and Street Name |
| Locality | Returns the Locality Name |
| Town | Returns the Post Town for this address |
| Raw Address Fields (unformatted with house number in a separate field) | |
| PAFSubBuilding | The sub building name |
| PAFBuilding | The building name |
| PAFNumber | Property number |
| PAFStreet | The street name |
| PAFLocality | The locality name |
| County Fields | |
| CountyPostal | Postal County (held, or formally held by Royal Mail) |
| CountyTraditional | Traditional County Name |
| CountyAdministrative | Administrative County Name |
| Additional Postal Fields | |
| DPS | Postal County (held by Royal Mail) |
| PostcodeType | L for Large User Postcode, S for Small User. |
| MailsortCode | Used for obtaining bulk mail discounts. |
| UDPRN | Royal Mail Unique Delivery Point Reference Number assigned to this letter box. |
| JustBuilt | AFDJustBuilt - Contains the date of inclusion on PAF for properties thought to be recently built. The date is stored numerically in descending format in the form YYYYMMDD. YYYY is the year, MM is the month and DD is the day. For example 20080304 is 04/03/2008. |
| Name Fields | |
| Gender | The gender (M or F) of the resident if known. |
| Forename | The first name of the resident |
| MiddleInitial | The middle initiate of the resident. |
| Surname | The surname/last name of the resident. |
| OnEditedRoll | Indicates if the resident is on the edited electoral roll (i.e. they have not opted out). Set to Y if the are on the Edited Roll, N if not, blank for Organisation and other records). To search set to #Y to return only records on the electoral roll, #N only for those not on the electoral roll or !N for all records including Organisations but excluding those not on the Edited Roll. |
| DateOfBirth | The residents date of birth if known (electoral roll attainers in the last 10 years only). |
| Residency | Gives time in years that the occupant has lived at this address. |
| HouseholdComposition | Describes the household composition of the selected address[4] |
| **Additional Organisation | Information Fields** |
| Business | Provides a description of the type of business |
| SICCode | Standard Industry Classification Code for an organisation record. |
| Size | Gives an indication of the number of employees of an organisation. [5] |
| Phone Number Related Fields | |
| Phone | Phone Number |
| Geographical Fields | |
| GridE | Grid Easting as a 6 digit reference |
| GridN | Grid Northing as a 6/7 digit reference |
| Latitude | Latitude representation of Grid Reference in Decimal Format (WGS84) |
| Longitude | Longitude representation of Grid Reference in Decimal Format (WGS84) |
| UrbanRuralCode | Provides a code which indicates if an area is mainly urban or rural and how sparsely populated those area’s are. [3] |
| UrbanRuralName | Provides a description which goes along with the UrbanRuralCode. [3] |
| Administrative Fields | |
| WardCode | Code identifying the electoral ward for this postcode |
| WardName | Name identifying the electoral ward for this postcode |
| AuthorityCode | Local/Unitary Authority for this Postcode (same as the start of the ward code). |
| AuthorityName | Local / Unitary Authority for this postcode |
| ConstituencyCode | Code for the Parliamentary Constituency for this postcode |
| ConstituencyName | Name of the Parliamentary Constituency for this postcode |
| EERCode | Code identifying the European Electoral Region for this postcode |
| EERName | Name identifying the European Electoral Region for this postcode |
| LEACode | Code identifying the Local Education Authority for this postcode |
| LEAName | Name identifying the Local Education Authority for this postcode |
| TVRegion | ISBA TV Region (not TV Company) |
| Postcode Level Property Indicator Fields | |
| Occupancy | Indication of the type of occupants of properties found on the selected postcode [1] |
| AddressType | Indication of the type of property level data to capture to have the full address for a property on the selected postcode. [2] |
| NHS Fields | NHSCode National Health Service Area Code |
| NHSName | National Health Service Area Name |
| NHSRegionCode | National Health Service Region Code |
| NHSRegionName | National Health Service Region Name |
| PCTCode | National Health Service Primary Care Trust Code for England (Local Health Board Code in Wales, Community Health Partnership in Scotland) |
| PCTName | Name matching the PCT Code field |
| Censation Fields | |
| CensationCode | Censation Code assigned to this Postcode |
| Affluence | Affluence description |
| LifeStage | LifeStage description |
| AdditionalCensusInfo | Additional information derived from the Census. |
[1] Possible Occupancy values and descriptions are as follows (information in brackets not part of the description):
[2] Possible Address Type values and descriptions are as follows (information in brackets not part of the description):
[3] The Urban Rural Code differs from England and Wales, Scotland and Northern Ireland. The possible codes and there meanings are as follows:
England & Wales
Scotland
Northern Ireland
[4] The household composition field includes both a number and description and can have any of the following values.
[5] The Size property can have any of the following values:
(If blank then this is unknown or not applicable).