Changeset 404

Timestamp:

Dec 3, 2006, 5:47:37 PM (14 years ago)

Author:

Nick Burch

Message:

Update API docs, and an associated tweak to the geocoder

Location:

trunk/npemap.org.uk

Files:

• cgi/geocoder.fcgi (modified) (2 diffs)
• static/api/geocoder.shtml (modified) (3 diffs)

trunk/npemap.org.uk/cgi/geocoder.fcgi

@@ -93 +93 @@
 
         # What postcode were they asking about?
-        if(defined $cgi->param("postcode")) {
+        if(defined $cgi->param("postcode") && $cgi->param("postcode")) {
                 $limit_results = 1;
                 $request{type} = "location";
@@ -105 +105 @@
                         next REQUEST;
                 }
-        } elsif(defined $cgi->param("easting") && defined $cgi->param("northing")) {
+        } elsif(defined $cgi->param("easting") && $cgi->param("easting") && 
+                defined $cgi->param("northing") && $cgi->param("northing")) {
                 $request{type} = "postcode";
                 $request{easting} = $cgi->param("easting");

trunk/npemap.org.uk/static/api/geocoder.shtml

@@ -8 +8 @@
 <h4>Geocoder</h4>
 
+<p>The geocoder supports various methods for turning postcodes into
+ locations, or locations into postcodes, using our collected data.</p>
+
+<h5>Postcode -&gt; Location</h5>
 <p>Look up the location that we have for a postcode. If we don't have an exact
 match for the postcode you request, then we will do our best. If we don't have
-an exact match, we will return #s where we don't have exact matches.
-</p>
+an exact match, we will return #s where we don't have exact matches.</p>
 
-<p> If you request the response with the format of 'js', then you can specify
+<h5>Location -&gt; Postcode</h5>
+<p>Look up the nearest postcode for a location. You can optionally get the
+ n nearest postcodes to a location.</p>
+
+<h5>Location -&gt; Postcode Areas</h5>
+<p>Look up the nearest postcode area (eg 'OX2') for a location. You can
+ optionally get the n nearest postcode areas to a location.</p>
+
+<h4>Result Formats</h4>
+<p>The results can be returned as plain text (csv with header), XML, or
+ javascript / javascript callback.</p>
+
+<p>If you request the response with the format of 'js', then you can specify
 the name of a funtion call to wrap around the JSON response. This will call
 that method with the JSON as a parameter. </p>
@@ -23 +38 @@
 <h4>Arguments</h4>
 <dl>
-<dt>postcode (required)</dt>
-<dd>The postcode that you wish the location of. You can enter just the outward part if you wish.</dd>
+<dt>postcode (required, unless easting and northing given)</dt>
+<dd>The postcode that you wish the location of. You can enter just the 
+ outward part if you wish.</dd>
+
+<dt>easting (required, unless postcode given)</dt>
+<dd>The easting part of the location, to find nearby postcodes or postcode
+ areas. If given, 'northing' must also be supplied.</dd>
+
+<dt>northing (required, unless postcode given)</dt>
+<dd>The northing part of the location, to find nearby postcodes or postcode
+ areas. If given, 'easting' must also be supplied.</dd>
+
+<dt>format (optional)</dt>
+<dd>The format to return the results in. Can be 'text', 'js' or 'xml'. The
+ default is plain text.</dd>
+
+<dt>results (optional)</dt>
+<dd>The number of results to return. The default is 1. (postcode to location
+ searching always returns one result).</dd>
+
+<dt>areas (optional)</dt>
+<dd>If searching by easting and northing, should postcodes be returned, or
+ should postcode areas be returned? The default is to return postcodes.</dd>
 
 </dl>
@@ -42 +78 @@
 
 <p>
-postcode: <input type="text" name="postcode" value="" size="30"> <br/>
+ postcode: <input type="text" name="postcode" value="" size="30" /> 
+ <i>or</i><br/>
+ easting: <input type="text" name="easting" value="" size="10" /> &nbsp;
+ northing: <input type="text" name="northing" value="" size="10" />
+</p>
+<p>
+ number of results: <input type="text" name="results" value="1" size="30" />
+ <br />
+ format:
+ <input id="format_text" type="radio" name="format" value="text"> <label for="format_text">Text</label>
+ <input id="format_js" type="radio" name="format" value="js" checked> <label for="format_js">JS</label>
+ <input id="format_xml" type="radio" name="format" value="xml"> <label for="format_xml">XML</label>
 
-format:
-<input id="format_text" type="radio" name="format" value="text"> <label for="format_text">Text</label>
-<input id="format_js" type="radio" name="format" value="js" checked> <label for="format_js">JS</label>
-<input id="format_xml" type="radio" name="format" value="xml"> <label for="format_xml">XML</label
-
-<input type="submit" value="Go" />
+ <input type="submit" value="Go" />
 </p>
 </form>