The AFD Common API provides full access to the AFD API for all our products. The API is easy to use and quick to implement, while balancing that with providing full flexibility. This enables you to rapidly develop using the API with practically any development environment to provide the data that you require. All AFD products provide rapid lookup and search functionality allowing you to implement address management solutions and provide bank data, account and card validation.
Our address management products are fully interchangeable with the Common API, meaning that you can include the name and all address fields in your integration even if you are only using our lowest level Postcode product. Your integration will then function fully with our Postcode Plus or Names & Numbers product should you, or your customer, wish to upgrade in the future. Similarly if you only develop for one product now, it’s easy to add fields and features from another later without having to learn a whole new API.
To make life as easy as possible, the AFD Common API comes with a Wizard which will generate sample projects and code for the major development environments and we are adding more each quarter. The AFD Common API is also backed up by our free customer support services. You can visit our website at www.afd.co.uk/support for full developer support with using our API.
You can download the API Wizard here.
We recommend that for the most rapid development and to help you know where to start that you use our API Wizard to generate a sample project for your development environment. If your environment is not one that is listed, then select one that is closest to your own and use that as a basis for your coding. By looking at a sample project you can get a look and feel for how the API works and what you can do with it and you can easily copy and paste the code from that into your own and adapt it to meet your needs. Our sample projects work in the way that your own application is most likely to work, but also keep code to an absolute minimum, whilst being well commented, so that you can transfer the code with ease. The API Wizard also provides the code to go into a module or class in your application with all our API declarations and constants included which you can copy and paste into your own application. The code for lookup and search functionality is also provided and can be similarly copied and pasted.
To load the Wizard, look for the AFD Common API Item on your start menu, under which you will find the API Wizard shortcut.
The first step in the Wizard allows you to select the type of AFD product you will be integrating with and the development environment that you are using. The AFD product types are as follows:
This includes AFD Postcode, Plotter, Postcode Plus, Names & Numbers, ZipAddress and WorldAddress. Functionality is also included for AFD Refiner which can be used to clean addresses if you have a Refiner API license. The same code generated can be used with any one or all of these products. You should select this option if you are looking for address management functionality – i.e. being able to lookup and search for addresses.
This is for integrations using our AFD BankFinder product. If you have BankFinder and wish to integrate this for looking up or searching for Bank details, validating account or card numbers then this is the option you will require.
This is for integrations for our AFD Nearest feature.
This is available with all our address management products which contain grid references (i.e. AFD Plotter, Postcode Plus and Names & Numbers). This allows you to utilise our Nearest feature to connect to your database of stores or customers to enable the nearest to be found by looking up a postcode, locality or town.
You can choose any of the following environments to integrate with. If the environment you require is not listed then please select that closest to your own to base your integration on. You should note that we are continually adding environments, so if you have one that you would like to see added, or are having problems integrating with, please contact our support team (www.afd.co.uk/support) for assistance.
For some environments you will also be given the option as to which type of integration you require. The options are as follows:
This is the most commonly used option and is used when the application is talking to our software directly on the local machine. This can be used with either desktop applications or client/server applications as long as the server used is the same one that our software is running on and you have the appropriate server license if applicable. This is the most direct method for calling our API.
Our XML API is perfect for server based integrations where either the language makes XML a more desirable delivery mechanism or in some cases, such as Java, is the only suitable mechanism. It is also ideal where you wish to have the AFD product running through PostcodeEverywhere (our XML Server) on a different machine to that which is running your application or you wish to use our own hosted or Postcode Internet Online per-click service. If you do not want to install the AFD software locally on a machine but wish to access it over the network through XML then again this solution is ideal. You will need to have a server license and have PostcodeEverywhere installed to use this functionality.
If you are integrating Nearest, the next stage of the Wizard will prompt you to select the database and specify the grid reference fields that you wish to connect to using the Common API. You can either connect using a DSN to an ODBC database source, or use the Database File option to choose an Access, FoxPro or Paradox table to use instead.
After specifying your database settings you should click the Connect button where the Wizard will attempt to connect to your database. When successful it will update the fields displayed below. For Nearest to work correctly you need to ensure the correct grid easting and northing fields are selected. These should be on the OS GB grid system. If you need to add grid reference fields to your database and populate it then please do this prior to running the Wizard and use the product front-end or AFD Refiner to add the grids to your database.
The Common API includes a List field to generate a string to display in a list of results for the user to select from. You should therefore select the fields from here that you wish to display in this List. We would recommend that either the Miles or Km field is included to provide the distance and then any other fields from your database that you desire. Alternatively you may decide to generate this yourself as all fields will be returned from Nearest or may not be using a list, but it may still be worth checking these to use for testing purposes.
A Primary Key field is also required to re-retrieve a record when selected from the list.
The next stage of the Wizard presents you some options related to how you wish the API to work with your application. Not all the options presented here are available with all product types and development types. Where an option does not appear it is not applicable in your case.
This allows you to select the format in which you require the address to be returned. Most developers will require the default Standard Fields option as this presents the address in the format most often used in labels and when writing an address. The Raw PAF fields provide the address in a raw format with, for example, the house number and building details separate. This can be useful for those capturing addresses for a database which stores addresses in this form. The BS7666 option provides addresses in the proposed BS 7666-5:2006 standard for a postal gazetteer allowing you to store addresses that conform to that standard (For more details on how our fields can be used to provide addresses in this standard, and other required meta data please see Appendix G of this manual). The USA Fields option is primarily intended for ZipAddress customers, but note that regardless of the format you use UK, USA and International addresses will be returned in that format.
For address management products you can also select the International fields option which is recommended if you are using International data as it provides not only the component address fields for international address data but also provides the address formatted for correct addressing and label printing so you are not left to try and format these for different countries yourself.
Note that BankFinder does not provide the proposed BS 7666-5:2006 format as it is not strictly applicable to that product which is not providing an address gazetteer.
Lookups and Searches can often produce multiple results from which the user will have to select the correct address or bank. The only time you do not have to worry about a list box is if you are solely going to validate account or card details in BankFinder without wishing to lookup branch details, even simple postcode lookups in our AFD Postcode product can sometimes yield multiple results as some postcodes contain more than one street.
Most developers will wish to include a list box on their form for this purpose and retain full control over layout, positioning and its look and feel. However, the option is also provided to use a list box provided by the API. The advantage of this is that if you wish to add a button, for example to lookup the address to an existing application, and be able to fill in the whole address without having to accommodate a list box or redesign an existing screen layout this can easily be achieved. It also makes the API simpler to integrate as you don’t have to worry about the facility to cancel long searches manage multiple results etc. – this is all done for you. Our example project and generated code make all this easy and should you opt to use the API’s own internal list box now it’s easy to change to use your own later by comparing the code. The internal list box will only be displayed when more than one result is returned for the user to choose from, or in the case of a long search so that the user is able to cancel it.
You should be aware that the API list box is only suitable for desktop applications that run on the same machine and desktop as the API as it will need to pop-up a window on the machine. Server applications will need to include their own list box and as such this option is not available when using XML solutions.
The facility to display error messages before returning to your own application is also included. This is most commonly used in conjunction with the facility to display the list box for you and means that in cases where an error occurs, such as no records found from a lookup, or an error opening the data files etc. this will be displayed to the user for you. The API Wizard includes the function to convert an error code to a string in the code generated for you, so displaying this yourself is easy, but if you’d like it done for you the option is there. Again this is only applicable to desktop applications.
When calling the Common API through the standard DLL (not using a Postcode Everywhere server) you can still make use of International data, if you have signed up to our International Service. This is done by the DLL passing lookups and searches where a non-UK country has been supplied to our server. To do this you will need to supply the serial number and password you were issued with for this service. You can also optionally include a userid which will identify this application.
When using the PostcodeEverywhere XML method of integration you will also be given a number of options required to connect to the PostcodeEverywhere server. These are not all required in all cases:
Server Name: If you are using our hosted service there is no need to change this setting. If you have your own server you will need to enter it’s name (as it will be accessible from your client machines) and include any port if not port 80, e.g. http://myserver:81
Serial Number: This is only required if you are using our hosted service (pce.afd.co.uk) or requiring International data (which must be passed to our server even if you are using your own for UK data). It is the serial number you were given on your license certificate when you purchased your license to use the service.
Password: Again this is only required if you are using our hosted service or International service and you should be aware of what this is if you have purchased a license for it.
User ID: This field is optional and allows you to identify the user or application that uses the service. For example you could use myapp to identify this application and myapp2 to identify another which could be helpful if you are reviewing logs later. Alternatively you could alter the sample code to modify this based on the user using your software.
The final option enables you to select the type of lookup that you require. It is easy to change this option in your code later as these are defined as constants. Please note that even if you take the option to only allow Postcode lookup’s, full code is still provided for searching by specific address fields so it is still possible to search for addresses when you don’t know the Postcode.
The lookup options are as follows:
This fully functional lookup mode allows the user the option to not only be able to enter a postcode in the lookup field, but also full find string’s, such as with address management products entering “Commercial Street, Birmingham” to find all records matching that string. In the case of Nearest a locality and/or town string can be entered. This includes looking up addresses from partial postcodes and attempts to fix common typing errors in postcodes entered. This mode provides the most functionality and provides rapid searching from the lookup field. With Address Management products it’s downside is that some lookup’s can take some time, particularly with Names & Numbers due to the quantity of data, and so while lookup’s can be canceled, in some cases you may prefer to restrict lookup’s further.
This mode enables you to lookup an address from its postcode (or zipcode), or by optionally including a property number, name or organisation name to narrow the lookup down (e.g. 304, B11 1AA). In AFD Postcode Plus, Names & Numbers and ZipAddress this will only return addresses matching the property specified. AFD Postcode and Plotter do not contain property data, however in this mode any number supplied will be returned with the address.
This method is the same as FastFind, but where a lookup for a locality or town results in multiple matches the user will be presented with a list of locations to choose from. When they select the one they want another lookup is carried out to find the nearest to the selected location.
This mode provides straight forward postcode (or zipcode) lookup functionality. The user can enter a full postcode (or zipcode) only and will get back a list of results on that postcode to select the address from (or in the case of Nearest will get the Nearest results to that postcode).
This is not applicable to a few development environments – please skip to section 3.5 if this is not displayed
The next stage enables you to generate an example project which contains all the code to carry out lookups and searches using your chosen product type and environment. You can use this to help get an idea as to how the integration works to decide how best to integrate your AFD product in your own application. If you are creating a new application you can use the example generated as a starting point for your own. Alternatively you can also easily include the code module or class included in the project in your own application and copy and paste code from the lookup and search buttons (and list box if applicable) into your own application.
Finally, you are given clickable links which will open a window from which you can copy and paste code into your own application. This is as an alternative from obtaining it from the example generated. You will always need to include the General declarations in a code module, or class as described (C++ environments have both a header (.h) and code (.cpp) file to include). You can then copy and paste the Lookup and Search code as desired.
Now that you have your sample project, if applicable, and sample code you can customize the integration as desired. The sample projects are based around a form, using a list box – but you can of course change this to output results to a file, a database etc. if desired. Should you wish to alter the settings that you have chosen you can re-run the Wizard and the comments provided in the code and module make it easy to customise the integration to suit your needs.
You may also wish to refer to our Common API Manual for full details of the API fields.
If you have a Refiner API license and wish to clean addresses you can easily see this too in the sample project. First add a new button next to the “Search” button. On the final “Implement Your Code” window select the “Clean Address” link and copy and paste the code into the Click event for that button. You can then enter an address to clean on the left and see the resulting cleaned address on the right.
We serve thousands of organisations and a network of hundreds of partners across multiple industry sectors, enabling them to have full confidence in their contact data.