Location: PHPKode > scripts > MyOSGB PHP Script > guide.html
<!DOCTYPE html>

<html>
  <head>
	<title>MyOSGB PHP Class - Usage Guide</title>
  </head>

  <body bgcolor="#f0f0f0">

		<div style="width: 750px; height: auto; margin: 20px auto 0px auto; text-align: left;">
			<h1>MyOSGB PHP Class</h1>
			<p>MyOSGB PHP Class is a simple lightweight PHP class written for PHP5. Its purpose is to simplify distance calculations between Eastings and Northings, National Grid References or a combination of all three. It can convert Eastings and Northings to National Grid References and vice-versa. All distance calculations are performed in miles, but there is an optional switch to change this to kilometers. It works exclusively on six digit (100 metre refrencing). Less than 6 will be padded with zeros, in order to force backwards compatibility between the different levels of refrencing. Grid refrences are genearted based on these different levels, but you can override this, if you wish to provide longer or shorter, albeit less accurate points of refrence, with or without spaces. This class is designed to work with the Ordnance Survey's National Grid referencing system only.<br /><br/>MyOSGB is <b>free</b> and released under the <b>GNU General Public License</b>. You can download it <a href="http://postcodepal.com/classes/myosgb.zip" title="myosgb.zip">here</a>.</p>

			<h2>Usage Guide</h2>
			<div class="hr"><hr /></div>

			<h3>Include / Initiate Class</h3>
			<p>Always include and initiate the class first.</p>

			<div style="background-color: #DEDEDE; padding-left:15px;">
			<code><span style="color: #000000">

			<span style="color: #0000BB">&lt;?php
			<br />
			<br /></span><span style="color: #007700">include(</span><span style="color: #DD0000">'class.myosgb.php'</span><span style="color: #007700">);&nbsp;</span><span style="color: #FF8000">//&nbsp;Include&nbsp;class
			<br />
			<br /></span><span style="color: #0000BB">$calc&nbsp;</span><span style="color: #007700">=&nbsp;new&nbsp;</span><span style="color: #0000BB">MyOSGB</span><span style="color: #007700">();&nbsp;</span><span style="color: #FF8000">//&nbsp;Initiate&nbsp;class

			<br />

			<br /></span><span style="color: #0000BB">?&gt;</span>
			</span></code>
			</div>

			<h3>GetGridRef()</h3>
			<p>This function takes a set of Eastings and Northings and returns the National Grid Reference based on the accuracy level. You can increase or decrease the accuracy level by supplying a number between 2-6 as a third parameter. All grid references by default are returned with spaces. If you provide the letter T as the final parameter, then these spaces will be trimmed.</p>

			<div style="background-color: #DEDEDE; padding-left:15px;">

			<code><span style="color: #000000">
			<span style="color: #0000BB">&lt;?php
			<br />
			<br />$gref&nbsp;</span><span style="color: #007700">=&nbsp;</span><span style="color: #0000BB">$calc</span><span style="color: #007700">-&gt;</span><span style="color: #0000BB">GetGridRef</span><span style="color: #007700">(</span><span style="color: #0000BB">529090</span><span style="color: #007700">,</span><span style="color: #0000BB">179645</span><span style="color: #007700">);&nbsp;</span><span style="color: #FF8000">//&nbsp;Returns&nbsp;TQ&nbsp;29090&nbsp;79645

			<br /></span><span style="color: #0000BB">$gref&nbsp;</span><span style="color: #007700">=&nbsp;</span><span style="color: #0000BB">$calc</span><span style="color: #007700">-&gt;</span><span style="color: #0000BB">GetGridRef</span><span style="color: #007700">(</span><span style="color: #0000BB">52909</span><span style="color: #007700">,</span><span style="color: #0000BB">17964</span><span style="color: #007700">);&nbsp;</span><span style="color: #FF8000">//&nbsp;Returns&nbsp;TQ&nbsp;2909&nbsp;7964
			<br /></span><span style="color: #0000BB">$gref&nbsp;</span><span style="color: #007700">=&nbsp;</span><span style="color: #0000BB">$calc</span><span style="color: #007700">-&gt;</span><span style="color: #0000BB">GetGridRef</span><span style="color: #007700">(</span><span style="color: #0000BB">5290</span><span style="color: #007700">,</span><span style="color: #0000BB">1796</span><span style="color: #007700">,</span><span style="color: #DD0000">'T'</span><span style="color: #007700">);&nbsp;</span><span style="color: #FF8000">//&nbsp;Returns&nbsp;TQ290796

			<br /></span><span style="color: #0000BB">$gref&nbsp;</span><span style="color: #007700">=&nbsp;</span><span style="color: #0000BB">$calc</span><span style="color: #007700">-&gt;</span><span style="color: #0000BB">GetGridRef</span><span style="color: #007700">(</span><span style="color: #0000BB">52</span><span style="color: #007700">,</span><span style="color: #0000BB">17</span><span style="color: #007700">,</span><span style="color: #0000BB">6</span><span style="color: #007700">,</span><span style="color: #DD0000">'T'</span><span style="color: #007700">);&nbsp;</span><span style="color: #FF8000">//&nbsp;TQ2000070000
			<br /></span><span style="color: #0000BB">$gref&nbsp;</span><span style="color: #007700">=&nbsp;</span><span style="color: #0000BB">$calc</span><span style="color: #007700">-&gt;</span><span style="color: #0000BB">GetGridRef</span><span style="color: #007700">(</span><span style="color: #0000BB">529090</span><span style="color: #007700">,</span><span style="color: #0000BB">179645</span><span style="color: #007700">,</span><span style="color: #0000BB">4</span><span style="color: #007700">);&nbsp;</span><span style="color: #FF8000">//&nbsp;Returns&nbsp;TQ&nbsp;291&nbsp;796

			<br /></span><span style="color: #0000BB">$gref&nbsp;</span><span style="color: #007700">=&nbsp;</span><span style="color: #0000BB">$calc</span><span style="color: #007700">-&gt;</span><span style="color: #0000BB">GetGridRef</span><span style="color: #007700">(</span><span style="color: #0000BB">529090</span><span style="color: #007700">,</span><span style="color: #0000BB">179645</span><span style="color: #007700">,</span><span style="color: #0000BB">5</span><span style="color: #007700">,</span><span style="color: #DD0000">'T'</span><span style="color: #007700">);&nbsp;</span><span style="color: #FF8000">//&nbsp;Returns&nbsp;TQ29097965

			<br />

			<br /></span><span style="color: #0000BB">?&gt;</span>
			</span></code>
			</div>

			<h3>GetGridRefCoords()</h3>
			<p>This function takes a National Grid Reference of any length or format and will return an array containing its Eastings and Northings in 6 digits (100 metre referencing). If an invalid grid reference is supplied then this function will return false, so it can also be used for grid reference validation. Some refrences for the North of Scotland will produce 7 digit northings. This is normal.</p>

			<div style="background-color: #DEDEDE; padding-left:15px;">

			<code><span style="color: #000000">
			<span style="color: #0000BB">&lt;?php
			<br />
			<br />$coords&nbsp;</span><span style="color: #007700">=&nbsp;</span><span style="color: #0000BB">$calc</span><span style="color: #007700">-&gt;</span><span style="color: #0000BB">GetGridRefCoords</span><span style="color: #007700">(</span><span style="color: #DD0000">'TQ&nbsp;29090&nbsp;79645'</span><span style="color: #007700">);
			<br /></span><span style="color: #FF8000">//&nbsp;Returns&nbsp;Array&nbsp;(&nbsp;[eastings]&nbsp;=&gt;&nbsp;529090&nbsp;[northings]&nbsp;=&gt;&nbsp;179645&nbsp;)&nbsp;

			<br />
			<br /></span><span style="color: #0000BB">$coords&nbsp;</span><span style="color: #007700">=&nbsp;</span><span style="color: #0000BB">$calc</span><span style="color: #007700">-&gt;</span><span style="color: #0000BB">GetGridRefCoords</span><span style="color: #007700">(</span><span style="color: #DD0000">'TQ&nbsp;2909&nbsp;7964'</span><span style="color: #007700">);
			<br /></span><span style="color: #FF8000">//&nbsp;Returns&nbsp;Array&nbsp;(&nbsp;[eastings]&nbsp;=&gt;&nbsp;529090&nbsp;[northings]&nbsp;=&gt;&nbsp;179640&nbsp;)&nbsp;

			<br />
			<br /></span><span style="color: #0000BB">$coords&nbsp;</span><span style="color: #007700">=&nbsp;</span><span style="color: #0000BB">$calc</span><span style="color: #007700">-&gt;</span><span style="color: #0000BB">GetGridRefCoords</span><span style="color: #007700">(</span><span style="color: #DD0000">'TQ290796'</span><span style="color: #007700">);
			<br /></span><span style="color: #FF8000">//&nbsp;Returns&nbsp;Array&nbsp;(&nbsp;[eastings]&nbsp;=&gt;&nbsp;529000&nbsp;[northings]&nbsp;=&gt;&nbsp;179600&nbsp;)&nbsp;

			<br />
			<br /></span><span style="color: #0000BB">$coords&nbsp;</span><span style="color: #007700">=&nbsp;</span><span style="color: #0000BB">$calc</span><span style="color: #007700">-&gt;</span><span style="color: #0000BB">GetGridRefCoords</span><span style="color: #007700">(</span><span style="color: #DD0000">'TQ'</span><span style="color: #007700">);
			<br /></span><span style="color: #FF8000">//&nbsp;Returns&nbsp;Array&nbsp;(&nbsp;[eastings]&nbsp;=&gt;&nbsp;500000&nbsp;[northings]&nbsp;=&gt;&nbsp;100000&nbsp;)&nbsp;

			<br />
			<br /></span><span style="color: #0000BB">$coords&nbsp;</span><span style="color: #007700">=&nbsp;</span><span style="color: #0000BB">$calc</span><span style="color: #007700">-&gt;</span><span style="color: #0000BB">GetGridRefCoords</span><span style="color: #007700">(</span><span style="color: #DD0000">'HY&nbsp;43709&nbsp;11495'</span><span style="color: #007700">);
			<br /></span><span style="color: #FF8000">//&nbsp;Returns&nbsp;Array&nbsp;(&nbsp;[eastings]&nbsp;=&gt;&nbsp;343709&nbsp;[northings]&nbsp;=&gt;&nbsp;1011495&nbsp;)&nbsp;

			<br />//&nbsp;Note:&nbsp;The&nbsp;above&nbsp;7&nbsp;digit&nbsp;northing&nbsp;is&nbsp;correct&nbsp;for&nbsp;this&nbsp;square.
			<br />
			<br /></span><span style="color: #0000BB">$coords&nbsp;</span><span style="color: #007700">=&nbsp;</span><span style="color: #0000BB">$calc</span><span style="color: #007700">-&gt;</span><span style="color: #0000BB">GetGridRefCoords</span><span style="color: #007700">(</span><span style="color: #DD0000">'IZ&nbsp;12345&nbsp;67890'</span><span style="color: #007700">);&nbsp;</span><span style="color: #FF8000">//&nbsp;Returns&nbsp;false

			<br />

			<br /></span><span style="color: #0000BB">?&gt;</span>
			</span></code>
			</div>

			<h3>GetDistanceBetweenCoords()</h3>
			<p>This function takes two sets of Eastings and Northings and returns the distance between them in miles. If you set <b>$calc->miles</b> to false, then the distance will be returned in kilometers. If you set <b>$calc->short</b> to false, then full distances will be returned. Short distances are always rounded.</p>

			<div style="background-color: #DEDEDE; padding-left:15px;">
			<code><span style="color: #000000">
			<span style="color: #0000BB">&lt;?php
			<br />
			<br />$distance&nbsp;</span><span style="color: #007700">=&nbsp;</span><span style="color: #0000BB">$calc</span><span style="color: #007700">-&gt;</span><span style="color: #0000BB">GetDistanceBetweenCoords</span><span style="color: #007700">(</span><span style="color: #0000BB">529090</span><span style="color: #007700">,</span><span style="color: #0000BB">179645</span><span style="color: #007700">,</span><span style="color: #0000BB">530047</span><span style="color: #007700">,</span><span style="color: #0000BB">179951</span><span style="color: #007700">);

			<br /></span><span style="color: #FF8000">//&nbsp;Returns&nbsp;0.62
			<br />

			<br /></span><span style="color: #0000BB">$distance&nbsp;</span><span style="color: #007700">=&nbsp;</span><span style="color: #0000BB">$calc</span><span style="color: #007700">-&gt;</span><span style="color: #0000BB">GetDistanceBetweenCoords</span><span style="color: #007700">(</span><span style="color: #0000BB">529090</span><span style="color: #007700">,</span><span style="color: #0000BB">179645</span><span style="color: #007700">,</span><span style="color: #0000BB">5300</span><span style="color: #007700">,</span><span style="color: #0000BB">1799</span><span style="color: #007700">);

			<br /></span><span style="color: #FF8000">//&nbsp;Returns&nbsp;0.59
			<br />

			<br /></span><span style="color: #0000BB">$distance&nbsp;</span><span style="color: #007700">=&nbsp;</span><span style="color: #0000BB">$calc</span><span style="color: #007700">-&gt;</span><span style="color: #0000BB">GetDistanceBetweenCoords</span><span style="color: #007700">(</span><span style="color: #0000BB">5290</span><span style="color: #007700">,</span><span style="color: #0000BB">1796</span><span style="color: #007700">,</span><span style="color: #0000BB">5300</span><span style="color: #007700">,</span><span style="color: #0000BB">1799</span><span style="color: #007700">);

			<br /></span><span style="color: #FF8000">//&nbsp;Returns&nbsp;0.65
			<br />

			<br /></span><span style="color: #0000BB">$calc</span><span style="color: #007700">-&gt;</span><span style="color: #0000BB">miles&nbsp;</span><span style="color: #007700">=&nbsp;</span><span style="color: #0000BB">false</span><span style="color: #007700">;&nbsp;</span><span style="color: #FF8000">//&nbsp;Switch&nbsp;to&nbsp;kilometers
			<br /></span><span style="color: #0000BB">$distance&nbsp;</span><span style="color: #007700">=&nbsp;</span><span style="color: #0000BB">$calc</span><span style="color: #007700">-&gt;</span><span style="color: #0000BB">GetDistanceBetweenCoords</span><span style="color: #007700">(</span><span style="color: #0000BB">529090</span><span style="color: #007700">,</span><span style="color: #0000BB">179645</span><span style="color: #007700">,</span><span style="color: #0000BB">530047</span><span style="color: #007700">,</span><span style="color: #0000BB">179951</span><span style="color: #007700">);

			<br /></span><span style="color: #FF8000">//&nbsp;Returns&nbsp;1.00
			<br />

			<br /></span><span style="color: #0000BB">$calc</span><span style="color: #007700">-&gt;</span><span style="color: #0000BB">miles&nbsp;</span><span style="color: #007700">=&nbsp;</span><span style="color: #0000BB">false</span><span style="color: #007700">;&nbsp;</span><span style="color: #FF8000">//&nbsp;Switch&nbsp;to&nbsp;kilometers
			<br /></span><span style="color: #0000BB">$calc</span><span style="color: #007700">-&gt;</span><span style="color: #0000BB">short&nbsp;</span><span style="color: #007700">=&nbsp;</span><span style="color: #0000BB">false</span><span style="color: #007700">;&nbsp;</span><span style="color: #FF8000">//&nbsp;Return&nbsp;full&nbsp;distances

			<br /></span><span style="color: #0000BB">$distance&nbsp;</span><span style="color: #007700">=&nbsp;</span><span style="color: #0000BB">$calc</span><span style="color: #007700">-&gt;</span><span style="color: #0000BB">GetDistanceBetweenCoords</span><span style="color: #007700">(</span><span style="color: #0000BB">529090</span><span style="color: #007700">,</span><span style="color: #0000BB">179645</span><span style="color: #007700">,</span><span style="color: #0000BB">530047</span><span style="color: #007700">,</span><span style="color: #0000BB">179951</span><span style="color: #007700">);
			<br /></span><span style="color: #FF8000">//&nbsp;Returns&nbsp;1.0047313073653

			<br />

			<br /></span><span style="color: #0000BB">?&gt;</span>
			</span></code>
			</div>

			<h3>GetDistanceBetweenGridRefs()</h3>
			<p>This function takes two National Grid Refrences and returns the distance between them in miles If you set <b>$calc->miles</b> to false, then the distance will be returned in kilometers. If you set <b>$calc->short</b> to false, then full distances will be returned. Short distances are always rounded.</p>

			<div style="background-color: #DEDEDE; padding-left:15px;">
			<code><span style="color: #000000">
			<span style="color: #0000BB">&lt;?php
			<br />
			<br />$distance&nbsp;</span><span style="color: #007700">=&nbsp;</span><span style="color: #0000BB">$calc</span><span style="color: #007700">-&gt;</span><span style="color: #0000BB">GetDistanceBetweenGridRefs</span><span style="color: #007700">(</span><span style="color: #DD0000">'TQ291796'</span><span style="color: #007700">,</span><span style="color: #DD0000">'TQ300800'</span><span style="color: #007700">);
			<br /></span><span style="color: #FF8000">//&nbsp;Returns:&nbsp;0.61
			<br />

			<br /></span><span style="color: #0000BB">$distance&nbsp;</span><span style="color: #007700">=&nbsp;</span><span style="color: #0000BB">$calc</span><span style="color: #007700">-&gt;</span><span style="color: #0000BB">GetDistanceBetweenGridRefs</span><span style="color: #007700">(</span><span style="color: #DD0000">'TQ&nbsp;29090&nbsp;79645'</span><span style="color: #007700">,</span><span style="color: #DD0000">'TQ&nbsp;30047&nbsp;79951'</span><span style="color: #007700">);
			<br /></span><span style="color: #FF8000">//&nbsp;Returns:&nbsp;0.62

			<br />

			<br /></span><span style="color: #0000BB">$distance&nbsp;</span><span style="color: #007700">=&nbsp;</span><span style="color: #0000BB">$calc</span><span style="color: #007700">-&gt;</span><span style="color: #0000BB">GetDistanceBetweenGridRefs</span><span style="color: #007700">(</span><span style="color: #DD0000">'TQ291796'</span><span style="color: #007700">,</span><span style="color: #DD0000">'TQ&nbsp;30047&nbsp;79951'</span><span style="color: #007700">);
			<br /></span><span style="color: #FF8000">//&nbsp;Returns:&nbsp;0.63
			<br />

			<br /></span><span style="color: #0000BB">$calc</span><span style="color: #007700">-&gt;</span><span style="color: #0000BB">miles&nbsp;</span><span style="color: #007700">=&nbsp;</span><span style="color: #0000BB">false</span><span style="color: #007700">;&nbsp;</span><span style="color: #FF8000">//&nbsp;Switch&nbsp;to&nbsp;kilometers
			<br /></span><span style="color: #0000BB">$calc</span><span style="color: #007700">-&gt;</span><span style="color: #0000BB">short&nbsp;</span><span style="color: #007700">=&nbsp;</span><span style="color: #0000BB">false</span><span style="color: #007700">;&nbsp;</span><span style="color: #FF8000">//&nbsp;Return&nbsp;full&nbsp;distances&nbsp;

			<br /></span><span style="color: #0000BB">$distance&nbsp;</span><span style="color: #007700">=&nbsp;</span><span style="color: #0000BB">$calc</span><span style="color: #007700">-&gt;</span><span style="color: #0000BB">GetDistanceBetweenGridRefs</span><span style="color: #007700">(</span><span style="color: #DD0000">'TQ291796'</span><span style="color: #007700">,</span><span style="color: #DD0000">'TQ&nbsp;30047&nbsp;79951'</span><span style="color: #007700">);
			<br /></span><span style="color: #FF8000">//&nbsp;Returns&nbsp;1.0099554445618
			<br />

			<br /></span><span style="color: #0000BB">?&gt;</span>
			</span></code>
			</div>

			<h3>GetDistanceBetweenCoordsAndGridRef()</h3>
			<p>This function takes a set of Eastings and Northings and a National Grid Refrence and returns the distance between them in miles If you set <b>$calc->miles</b> to false, then the distance will be returned in kilometers. If you set <b>$calc->short</b> to false, then full distances will be returned. Short distances are always rounded. The order of the supplied parameters here is completely irrelevant.</p>

			<div style="background-color: #DEDEDE; padding-left:15px;">
			<code><span style="color: #000000">
			<span style="color: #0000BB">&lt;?php
			<br />
			<br />$distance&nbsp;</span><span style="color: #007700">=&nbsp;</span><span style="color: #0000BB">$calc</span><span style="color: #007700">-&gt;</span><span style="color: #0000BB">GetDistanceBetweenCoordsAndGridRef</span><span style="color: #007700">(</span><span style="color: #0000BB">529090</span><span style="color: #007700">,</span><span style="color: #0000BB">179645</span><span style="color: #007700">,</span><span style="color: #DD0000">'TQ300800'</span><span style="color: #007700">);
			<br /></span><span style="color: #FF8000">//&nbsp;Returns:&nbsp;0.61

			<br />

			<br /></span><span style="color: #0000BB">$distance&nbsp;</span><span style="color: #007700">=&nbsp;</span><span style="color: #0000BB">$calc</span><span style="color: #007700">-&gt;</span><span style="color: #0000BB">GetDistanceBetweenCoordsAndGridRef</span><span style="color: #007700">(</span><span style="color: #DD0000">'TQ&nbsp;29090&nbsp;79645'</span><span style="color: #007700">,</span><span style="color: #0000BB">530047</span><span style="color: #007700">,</span><span style="color: #0000BB">179951</span><span style="color: #007700">);
			<br /></span><span style="color: #FF8000">//&nbsp;Returns:&nbsp;0.62

			<br />

			<br /></span><span style="color: #0000BB">$distance&nbsp;</span><span style="color: #007700">=&nbsp;</span><span style="color: #0000BB">$calc</span><span style="color: #007700">-&gt;</span><span style="color: #0000BB">GetDistanceBetweenCoordsAndGridRef</span><span style="color: #007700">(</span><span style="color: #0000BB">530047</span><span style="color: #007700">,</span><span style="color: #DD0000">'TQ291796'</span><span style="color: #007700">,</span><span style="color: #0000BB">179951</span><span style="color: #007700">);
			<br /></span><span style="color: #FF8000">//&nbsp;Returns:&nbsp;0.63
			<br />

			<br /></span><span style="color: #0000BB">$calc</span><span style="color: #007700">-&gt;</span><span style="color: #0000BB">miles&nbsp;</span><span style="color: #007700">=&nbsp;</span><span style="color: #0000BB">false</span><span style="color: #007700">;&nbsp;</span><span style="color: #FF8000">//&nbsp;Switch&nbsp;to&nbsp;kilometers
			<br /></span><span style="color: #0000BB">$calc</span><span style="color: #007700">-&gt;</span><span style="color: #0000BB">short&nbsp;</span><span style="color: #007700">=&nbsp;</span><span style="color: #0000BB">false</span><span style="color: #007700">;&nbsp;</span><span style="color: #FF8000">//&nbsp;Return&nbsp;full&nbsp;distances&nbsp;

			<br /></span><span style="color: #0000BB">$distance&nbsp;</span><span style="color: #007700">=&nbsp;</span><span style="color: #0000BB">$calc</span><span style="color: #007700">-&gt;</span><span style="color: #0000BB">GetDistanceBetweenCoordsAndGridRef</span><span style="color: #007700">(</span><span style="color: #0000BB">529090</span><span style="color: #007700">,</span><span style="color: #0000BB">179645</span><span style="color: #007700">,</span><span style="color: #DD0000">'TQ300800'</span><span style="color: #007700">);
			<br /></span><span style="color: #FF8000">//&nbsp;Returns&nbsp;0.97679322274471
			<br />

			<br /></span><span style="color: #0000BB">?&gt;</span>
			</span></code>
			</div>

			<br />

			<p align="center">Copyright &copy; 2011 Vulcan Logix. All rights reserved.</p>

			<br />

			<div class="hr"><hr /></div>
		</div>

	<br />

  </body>
</html>
Return current item: MyOSGB PHP Script