Configuration
The Address Finder must be configured via the Jadu Control Centre by an administrative user. The following configuration options can be set:
| Option | Description | Example value |
|---|---|---|
| Authentication Key | API key used by Jadu when making API requests | |
| Configuration file location | URL for the location of the configuration JSON file (see below). Must be https. | https://example.com/address-finder/config.json |
| Configuration cache timeout | Period of time in seconds to cache configuration data before re-fetching from the URL above. | 86400 (24 hours) |
| Lookup cache timeout | Period of time in seconds to cache lookup result data before re-fetching. | 86400 (24 hours) |
| Enabled | Whether or not this integration should be used | On / off |
Configuration file
The configuration file should contain the following details as a JSON object.
| Option | Description | Example value | Required |
|---|---|---|---|
| base_uri | Base URI for all other API paths. This should be https. | Yes | |
| status_path | Relative URI to endpoint that provides status information for the API | /status | Yes |
| property_lookup | Container of property lookup URI configuration | ||
| property_lookup.search_path | Relative URI to the endpoint to use for property search requests. The {postcode} placeholder can be used to define where in the URI the postcode being searched for is placed. |
/property/search/{postcode} | |
| property_lookup.fetch_path | Relative URI to the endpoint to use to fetch a single property by its identifier. The {identifier} placeholder can be used to define where in the URI the id being fetched is placed. |
/property/fetch/{identifier} | |
| street_lookup | Container of street lookup URI configuration | ||
| street_lookup.search_path | Relative URI to the endpoint to use for street search requests. The {term} placeholder can be used to define where in the URI the term being searched for is placed. |
/street/search/{term} | |
| street_lookup.fetch_path | Relative URI to the endpoint to use to fetch a single street record by its identifier. The {identifier} placeholder can be used to define where in the URI the id being fetched is placed. |
/street/fetch/{identifier} |
When the property_lookup section is present and contains valid values for both search_path and fetch_path, the API will be used for property type address lookups.
When the street_lookup section is present and contains valid values for both search_path and fetch_path, the API will be used for street type address lookups.
Developers can therefore control how the API is used by returning configuration for only the section(s) they have implemented.
Example JSON configuration contents:
{
"base_uri": "https://example.com/address-finder",
"status_path": "/status",
"property_lookup": {
"search_path": "/property/search/{postcode}",
"fetch_path": "/property/fetch/{identifier}"
},
"street_lookup": {
"search_path": "/street/search/{term}",
"fetch_path": "/street/fetch/{identifier}"
}
}
Validation
Upon saving the configuration settings, Jadu will attempt to retrieve the configuration file from the given location. The service should respond with an HTTP 200 OK status and a response body containing the JSON configuration (see example above).
Any non-200 response code will be treated as an error and logged. Additionally, if Jadu is not able to parse the response body into a JSON object, an error will be logged. If either of these errors occur, the integration will be prevented from being enabled.
An HTTP GET request is then sent to the status_path URI defined in the configuration file. If this request times out or responds with anything other than HTTP 200 OK, a validation error is returned.