modules/geonames/GeoNames_API.txt

$id$

Geonames API Documentation, by Erlend Eide erlend (|) edesign.no

Defining new services: Service Definitions (Service Modules)
--------------------------------------------------------------------------------
The geonames_MODULENAME_geoconfig function must return configuration data. 
The configuration is an array with the following set of properties defined
in an associative array (see below the list for explanations):

 - service_name             string               name to refer to in code
 - service_full_name        string               Human Readable Name
 - description              string               Human Readable Description
 - service_path             string               Geonames Service Location (path)
 - credit_cost              int                  Commercial Services Credit Price
 - result_cache_prefix      string               Unique cache prefix (end with :)
 - data_cache_prefix        string               Unique cache prefix (end with :)
 - allowed_parameters       associative array    see below
 - array_parameters         array of strings     optional, see below
 - required_parameters      array of strings     optional, see below
                            or array of array   
 - required_parameters_type string               mandatory if required_parameters
 - query_defaults           associative array    optional, see below
 - columns                  array of strings     mandatory if no style is set
 - pager                    boolean              optional, see below
 - detect_style             boolean              optional, see below

Parameter: allowed_parameters (associative array) 
This array defines which parameters are allowed in queries, all other parameters
will be omitted from the query. The array must be associative, where the key is 
"our" parameter name (Drupal style, lowercase) and the value is GeoNames style 
(mixedCase). 
All services that support the style parameter (short/medium/full/long) should
have the parameter detect_style set to TRUE, unless the query default value 
for style allways is to be used.
This structure allows the GeoNames API to use other parameter names than the 
actual GeoNames Service -- for instance GeoNames' "q" parameter should allways
be named "query" when we refer to it in Drupal. This will prevent Drupal's
q=node/x parameter to be added to the array if the query is passed by URL.

Parameter: array_parameters (array of strings)
Any parameter specified here will allow the parameter to be an array. Some of
the GeoNames Services allow several equally named parameters to be sent -- for
instance the Fulltext Search service. You may for instance specify several
Countries to restrict your query to. The result is several equally named 
parameters in the query URL passed to Geonames (i.e. &country=NO&country=SE)

Parameter: required_parameters (array of strings OR array with arrays of strings)
Some services have several sets of requirements, therefore we may specify this
parameter as an array with arrays of strings.
Each subset (or just the single set) will be used to verify if the query 
contains the required parameters. In this way, we prevent requests to GeoNames
that will just return error messages.

Parameter: required_parameters_type (string)
The string may be either 'single' or 'all'. This parameter is required if the
parameter "required_parameters" is set.
Single: One of the parameters in required_parameters is mandatory
All: All of the parameters defined in required_parameters are mandatory

Parameter: query_defaults (associative array)
This associative array is optional. When set, the key/value pairs will be added
as default query parameters to a request. The values may be overridden by the 
user-specified query (if $columns is passed in the geonames_query).

Parameter: columns (array of strings)
This parameter is mandatory if the query parameter 'style' is not available, or
set, in the required_parameters. If style is set, columns is optional. The field
names specified here will be added to your results (and all others will be 
ignored). The parameter may be overridden by the user-specified query (if 
$columns is passed in the geonames_query)

Parameter: detect_style (boolean)
This optional parameter may be set to TRUE if the service supports the 
short/medium/long/full styles. The API will (based on the $columns passed in the
geonames_query) automatically detect the style that should be requested. The 
purpose of the detection is to minimize the amount of data requested from the 
GeoNames server.

Parameter: pager (boolean)
This optional parameter may be set to TRUE if you want/need to calculate pager 
data for the results. The result object will get an extra property $result->pager
which contains everything you need to set up a set of pages.
1	$id$
2
3	Geonames API Documentation, by Erlend Eide erlend (\|) edesign.no
4
5	Defining new services: Service Definitions (Service Modules)
6	--------------------------------------------------------------------------------
7	The geonames_MODULENAME_geoconfig function must return configuration data.
8	The configuration is an array with the following set of properties defined
9	in an associative array (see below the list for explanations):
10
11	- service_name string name to refer to in code
12	- service_full_name string Human Readable Name
13	- description string Human Readable Description
14	- service_path string Geonames Service Location (path)
15	- credit_cost int Commercial Services Credit Price
16	- result_cache_prefix string Unique cache prefix (end with :)
17	- data_cache_prefix string Unique cache prefix (end with :)
18	- allowed_parameters associative array see below
19	- array_parameters array of strings optional, see below
20	- required_parameters array of strings optional, see below
21	or array of array
22	- required_parameters_type string mandatory if required_parameters
23	- query_defaults associative array optional, see below
24	- columns array of strings mandatory if no style is set
25	- pager boolean optional, see below
26	- detect_style boolean optional, see below
27
28	Parameter: allowed_parameters (associative array)
29	This array defines which parameters are allowed in queries, all other parameters
30	will be omitted from the query. The array must be associative, where the key is
31	"our" parameter name (Drupal style, lowercase) and the value is GeoNames style
32	(mixedCase).
33	All services that support the style parameter (short/medium/full/long) should
34	have the parameter detect_style set to TRUE, unless the query default value
35	for style allways is to be used.
36	This structure allows the GeoNames API to use other parameter names than the
37	actual GeoNames Service -- for instance GeoNames' "q" parameter should allways
38	be named "query" when we refer to it in Drupal. This will prevent Drupal's
39	q=node/x parameter to be added to the array if the query is passed by URL.
40
41	Parameter: array_parameters (array of strings)
42	Any parameter specified here will allow the parameter to be an array. Some of
43	the GeoNames Services allow several equally named parameters to be sent -- for
44	instance the Fulltext Search service. You may for instance specify several
45	Countries to restrict your query to. The result is several equally named
46	parameters in the query URL passed to Geonames (i.e. &country=NO&country=SE)
47
48	Parameter: required_parameters (array of strings OR array with arrays of strings)
49	Some services have several sets of requirements, therefore we may specify this
50	parameter as an array with arrays of strings.
51	Each subset (or just the single set) will be used to verify if the query
52	contains the required parameters. In this way, we prevent requests to GeoNames
53	that will just return error messages.
54
55	Parameter: required_parameters_type (string)
56	The string may be either 'single' or 'all'. This parameter is required if the
57	parameter "required_parameters" is set.
58	Single: One of the parameters in required_parameters is mandatory
59	All: All of the parameters defined in required_parameters are mandatory
60
61	Parameter: query_defaults (associative array)
62	This associative array is optional. When set, the key/value pairs will be added
63	as default query parameters to a request. The values may be overridden by the
64	user-specified query (if $columns is passed in the geonames_query).
65
66	Parameter: columns (array of strings)
67	This parameter is mandatory if the query parameter 'style' is not available, or
68	set, in the required_parameters. If style is set, columns is optional. The field
69	names specified here will be added to your results (and all others will be
70	ignored). The parameter may be overridden by the user-specified query (if
71	$columns is passed in the geonames_query)
72
73	Parameter: detect_style (boolean)
74	This optional parameter may be set to TRUE if the service supports the
75	short/medium/long/full styles. The API will (based on the $columns passed in the
76	geonames_query) automatically detect the style that should be requested. The
77	purpose of the detection is to minimize the amount of data requested from the
78	GeoNames server.
79
80	Parameter: pager (boolean)
81	This optional parameter may be set to TRUE if you want/need to calculate pager
82	data for the results. The result object will get an extra property $result->pager
83	which contains everything you need to set up a set of pages.