Getting Started with LightRod

From LightRod

Jump to: navigation, search

See the description of this software here.


Download, unpack the source PHP files into your project directory on your web server. Copy oar-server/cls.basic_geosearch.php into your main path (or alternatively refer to it below from within the LightRod source tree).


Contents

Preparation

  • Create a table with your points, and latitude, longitude, e.g. tbl_points (int_point_id, dec_latitude, dec_longitude).

Note: You can use any field/table names

  • Add four 32-bit integer columns called e.g. int_peano1, int_peano2, int_peano1iv, int_peano2iv. (or any alternative names)
  • Add multi-column indexes to your table on 
(int_peano1, int_point_id)
(int_peano2, int_point_id)
(int_peano1iv, int_point_id)
(int_peano2iv, int_point_id)

Generate the peano codes before searching against the table (this can be done each time a new entry is added, or once at the beginning): 

require("cls.basic_geosearch.php");
$bg = new clsBasicGeosearch();
$peano1 = $bg->generate_peano1($latitude, $longitude);		//Lat/lon of point in table
$peano2 = $bg->generate_peano2($latitude, $longitude);
$peano1iv = $bg->generate_peano_iv($peano1);
$peano2iv = $bg->generate_peano_iv($peano2);

and then write these values back into the table.



Most basic use

Carry out a search using the following example: 

require("cls.basic_geosearch.php");
$bg = new clsBasicGeosearch();

$params = array('latitude' => 50.00,			//Latitude in decimal degrees of center of search
		'longitude' => 120.00,			//Longitude in decimal degrees of center of search 
		'table_name' => "tbl_points",		//Main table name that is being searched on 
		'id_field' => "int_point_id",		//Unique reference to each point in the table
		'latitude_field' => "dec_latitude",	//Field in table that has the latitude in decimal
		'longitude_field' => "dec_longitude",	//Field in table that has the longitude in decimal
		'peano_field_header' => "int_peano"	//First letters of fields in table that hold peano
                                                        //integers E.g. 'int_peano', which gets appended
			 				//to create 'int_peano1, int_peano2, int_peano1iv,
			 				// int_peano2iv'	
		);
		

$results_array = $bg->proximity_finder($params);

Returned values

$results_array[] - the list of results and the included fields 

	
foreach($results_array as $result) {

	echo $result['int_point_id'] . ", Dist: " . $result['dist'] .
            ", Lat: " . $result['latitude'] . ", Lon: " . $result['longitude'] . "<br>";

}

Additional Return Fields

(Optional, if 'provide_count' => true)

For a search such as: 

$params = array( [...fields here...]
		'provide_count' => true
		);
	
list($results_array, $count) = $bg->proximity_finder($params);

Returns: 

$count['precise_in_display']            - precise number of results to display on this page (usually 1-10) 
$count['next_record_group']		- value to give $first_record on a 'More results' link
$count['previous_record_group']		- value to give $first_record on a 'Previous results' link
$count['coarse_matches']		- if $provide_count = true, total number of matches, approximation 
					- uses $whole_data_dist and $max_total_results
$count['show_next']			- true or false, for showing a 'More Results' link
$count['show_previous']			- true or false, for showing a 'Previous Results' link

API

Required fields

latitude

Latitude in decimal degrees of center of search eg. 50.554345 (-90.0 to 90.0).

longitude

Longitude in decimal degrees of center of search eg. 20.554345 (-180.0 to 180.0).

table_name

Main table name that is being searched on e.g. 'tbl_my_points'.

id_field

Unique reference to each point in the table e.g. 'int_point_id'.

latitude_field

Field in table that has the latitude in decimal for each point e.g. 'dec_latitude' which holds values such as 50.554345.

longitude_field

Field in table that has the longitude in decimal for each point e.g. 'dec_longitude' which holds values such as 20.554345.

peano_field_header

First letters of fields in table that hold peano integers. E.g. 'int_peano', which gets appended to create 'int_peano1, int_peano2, int_peano1iv, int_peano2iv'.


Optional Fields

misc_fields

Miscellaneous fields to be selected and put into the results e.g. "var_point_title, var_point_description, j.var_my_join_field". This is usually from the same table, but can be from different tables that are joined with 'custom_join' below. Default: "".

first_record

First record to search from. After clicking 'more' would set this to say 10. Default: 0.

max_records

Maximum number of results to display. Default: 10.

provide_count

Provide an approximate count of the results found, and other details such as whether there is a next page of results. The accuracy varies because it is doesn't count the results. The count is returned in a second array. Default: false.

start_record_group

This functionality is not yet working - once reached the end of the sample of results we can look into the next bunch - usually incremented about 200 at a time. Default: 0.

custom_where

Limit the results to this set e.g. "int_code = 5". Default: "".

custom_join

Include a SQL join to other tables, (after the results have been found), and a SQL WHERE clause or GROUP BY clause. e.g. 

	 "JOIN tbl_point_details pd ON m.int_point_details_id = pd.int_point_details_id
	 WHERE pd.int_param > 10"

Default: "". The main table you are joining off is called 'm' (short for marker), which is your table in the 'table_name' parameter.

show_queries

Switch to 'true' to print queries in search to screen for debugging. Default: false.

units

'mi' or 'km' for search results units. Default: "km".

radius

=0 means no radius applied, otherwise limit results within this many km or miles. See 'radius_units'. Default:0.

radius_units

'mi' or 'km' of the radius to search within. Default: "km".

decimal_places

Precision of results displayed, 2 would give 50.32. Default: 1.

get_dist_bearing

5 mi _NE_, shows the bearing towards the result e.g. 'NE'. false switches this off. Default: true.

relevancy_field

Field in table that corresponds to a relevancy, that is combined with proximity to sort the results e.g. "int_value". Default: "".

relevancy_scaler

A max value that scales the results. Can include a '-' to be inverted relevancy. Default: "".

sort_order

Proportion of result ordering devoted to the relevancy field i.e. 0.0 = no relevancy field influence, all geo-proximity influence, 1.0 = all relevancy field influence, no geo-proximity influence. Default: 0.0.

index_and

These fields are a part of the main peano database index, and reduce the result set grabbed initally before the results are restricted e.g. "int_country_id = 5". Default: "".

final_sort_field

Sort the last set of 10 results, right at the end of the process by this field. Useful for sorting by e.g. price. Note: on clicking the 'Next', the results will be sorted within the next 10, so the flow of results won't be perfect. Note 2: can include ' DESC' to sort descending e.g. 'int_my_sort DESC'. Default: "".

whole_data_dist

Distance in degrees around the planet that the whole dataset covers. Used to help approximate the count of results. If you have global coverage, use (full world lat+lon would be = 90+180 = 270). Default: 20.

max_total_results

Maximum total results, used to prevent total results becoming so large with the approximation that it is non-sensical. Usually set to the number of records in the search table. Default: 1000000.

peano1_field

Optional flexible peano field names e.g. "int_peano1". Default: "".

peano2_field

e.g. "int_peano2". Default: "".

peano1iv_field

e.g. "int_peano1iv". Default: "".

peano2iv_field

e.g. "int_peano2iv". Default: "".

Retrieved from "http://www.lightrod.org/mediawiki/index.php/Getting_Started_with_LightRod"
Personal tools