Unthrottled XML port API. You must sign up to use this port. (Cost: $1 for 400 lookups. Lookup credits, once purchased never expire. We do not charge credits for lookups that fail to return a definite response)
Geocoder.ca provides a simple XML interface to do real-time automated geocoding for your application.
Geocoding API : Reverse Geocoding API - Intersection Geocoding API - [User supplied coding and documentation material ]
Main Geocoding server: geocoder.ca | Backup geocoding server: backup-geocoder.ca
Specifications:
Input
The following parameters must be sent to http://geocoder.ca using either a GET or POST HTTP method.
Parameter Name Description Permitted Values
auth
The authentication code for unthrottled service.
A string up to 30 bytes long. This code identifies you as a premium user and keeps track of the number of lookups you make.
addresst
The name of the street address.
A string no longer that 220 bytes.
stno
Street Number
A number.
city
The City Name
A string no longer that 220 bytes.
prov
The Two letter Canadian province code or US state abbreviation.
(AB,BC,MB,NB,NL,NS,NT,NU,ON,PE,QC,SK,YT)
locate
Optionally you can specify a location. for example 330 metcalfe ottawa or metcalfe & wellington ottawa
This is an optional parameter for your convenience. We will parse out an address or intersection from it.
strict
Optional Parameter for enabling strict parsing of free form location input.
1.
standard
Return the properly formated "standartized" address in the response.
This is an optional parameter for address standardization. There is only one valid value: 1
decimal
An integer positive number.
This is an optional parameter to limit the number of decimal places in the response. (note that a small number will reduce accuracy)
postal
A six letter canadian postal code
The postal code format should follow the following format ANANAN where N represents a number and A a letter.
geoit
The output type desired.
Only one allowed value: XML
id
optionally you can include your own transaction id. this will be returned along with the response if provided.
a number or string no longer that 15 bytes.
strictmode
Optionally you can prevent geocoder from making guesses on your input - for example if you enter just a city name without the state or province, instead of geocoder determining the most likely city, it will let you chose from a list of suggestions.
Allowed values are Integer 0 or 1.
showpostal
Optionally - If you supply just a street address (or intersection), the showpostal parameter will instruct the algorithm to return the postal code of the location along with the latitude/longitude pair.
Only one allowed value: 1
topmatches
Optionally - If you supply a partial street address and wish to obtain a fixed number of the most likely suggestions, send a
value through this parameter.
This must be the maximum number of suggestions desired in the response. The topmatches parameter value must be a positive integer.
Input Requirements:
You must provide your authentication code (auth ) and either a street address (addresst , stno , city , prov ) or a postal code (postal ).
The parameter geoit =XML is also required.
Output
The output may contain the following XML formated parameters.
Parameter Name Description Expected Output Values
latt
The latitude.
A decimal number.
longt
The longitude.
A decimal number.
remaining_credits
The remaining lookup credits in your account.
An integer number. The minimum value is -100. This is to give you some "buffer" zone and ample notice to replenish your lookup credits in case your balance runs low. If the remaining credits drops below -100 you will not be able to make any more unthrottled lookups. If that happens you may login to your account to obtain more credits.
id
Transaction id.
If supplied in the input the transaction id will be returned along with the output.
stnumber
In case you requested a properly formated address to be returned.
The street number (integer value).
staddress
In case you requested a properly formated address to be returned.
The formated street address.
city
In case you requested a properly formated address to be returned.
The city name.
prov
In case you requested a properly formated address to be returned.
The province code.
Error Codes:
The output could contain an error code. If your query does not produce coordinates the latt and longt containers will be empty.
001
ip_address is not allowed to use authentication token: auth
002
auth has ran out of credits.
(in case you have used over 100 credits over your total balance)
003
Authentication token: auth not found.
005
Postal Code is not in the proper Format.
004
Specify either a Canadian province two letter code or a US two letter state abbreviation.
007
Supply a valid query.
008
Your request did not produce any results. Check your spelling and try again.
Sometimes when a location is not found a suggestion (or more) will be contained within <suggestion> xml tags. for example:
<geodata>
<error>
<code>008</code>
<description>Your request did not produce any results. Check your spelling and try again.</description>
</error>
<suggestion>
<stno>5993</stno>
<addresst>Meadowglen Drive</addresst>
<city>ottawa</city>
<prov>ON</prov>
</suggestion>
</geodata>
or
http://geocoder.ca/?locate=Thornton&geoit=xml&standard=1&topmatches=1&strictmode=1
<<geodata>gt;
<<error>gt;
<<code>gt;101<</code>gt;
<<description>gt;
Ambiguity in input. Several possible cities match your query.
<</description>gt;
<</error>gt;
<<possiblecity>gt;Thornton, NE<</possiblecity>gt;
<<possiblecity>gt;Thornton, CO<</possiblecity>gt;
<<possiblecity>gt;Thornton, WA<</possiblecity>gt;
<</geodata>gt;
in case the topmatches parameter is supplied, the most likely matches will be returned up to the number requested.
for example, this request will return the top 5 suggestions for the following improperly formed address:
Note: 1 successful lookup costs 1 credit. You can buy 4 credits for 1c. We do not charge for lookups that fail to return coordinates for whatever reason.
Cross Street Intersection Geocoding Specifications:
Input
The following parameters must be sent to http://geocoder.ca using either a GET or POST HTTP method.
Parameter Name Description Permitted Values
street1
The name of the first street
A string no longer that 220 bytes.
street2
The name of the second street
A string no longer that 220 bytes.
city
The City Name
A string no longer that 220 bytes.
prov
The Two letter Canadian province code or two letter US state abbreviation.
(AB,BC,MB,NB,NL,NS,NT,NU,ON,PE,QC,SK,YT)
locate
Optionally you can specify a location. for example 330 metcalfe ottawa or metcalfe & wellington ottawa
This is an optional parameter for your convenience. We will parse out an address or intersection from it.
decimal
An integer positive number.
This is an optional parameter to limit the number of decimal places in the response. (note that a small number will reduce accuracy)
cross
A boolean value indicating the type of geocoding desired.
an integer of value 1
geoit
The output type desired.
Only one allowed value: XML
id
optionally you can include your own transaction id. this will be returned along with the response if provided.
a number or string no longer that 15 bytes.
showpostal
Optionally - If you supply just a street address (or intersection), the showpostal parameter will instruct the algorithm to return the postal code of the location along with the latitude/longitude pair.
Only one allowed value: 1
Output
xx.yyyyyyyyy
-xx.yyyyyyyyy
City Name
Two letter province code
Street1
Street2
number of remaining credits : integer value
Possible extra Error Codes related to intersection geocoding.
010
Two streets, the province and the city name are required.
Suggestion System:
Sometimes a suggestion will be provided upon an unsucessful request.
for example:
Reverse Geocoding Specifications:
Input
For performing reverse geocoding The following parameters must be sent to http://geocoder.ca using either a GET or POST HTTP method.
Parameter Name Description Permitted Values
latt
The Latitude.
A decimal number.
longt
The Longitude.
A decimal number.
range
The optional range to limit the reverse geocoding.
A number.
moreinfo
The optional moreinfo parameter will cause the xml port to return the county and metro area information.
1.
allna
The optional allna parameter indicates that you wish to perform the reverse geocoding in both the USA and Canada, in some cases (for areas close to the border) obtaining two results instead of one. This parameter is also required for reverse geocoding in the US.
1.
decimal
An integer positive number.
This is an optional parameter to limit the number of decimal places in the response. (note that a small number will reduce accuracy)
reverse
An integer indicating your interface preference.
valid values is integer 1.
geoit
The output type desired.
Only one allowed value: XML
id
optionally you can include your own transaction id. this will be returned along with the response if provided.
a number or string no longer that 15 bytes.
corner
Optionally you can obtain the nearest street intersection to a latitude/longitude pair.
Only one allowed value: 1
Input Requirements:
You must provide a latitude-longitude pair and the reverse and geoit parameters.
Output
The output will contain these parameters in XML format.
Parameter Name Description Expected Output Values
latt
The latitude of the result.
A decimal number.
longt
The longitude of the result.
A decimal number.
city
The city of the result set
prov
The province
postal
The postal code.
stnumber
The street number.
staddress
The street address.
inlatt
The input latitude.
inlongt
The input longitude.
distance
The distance of the result location from the input location.
NearRoad
The nearest Road to the input point.
NearRoadDistance
The distance of the nearest Road to the input point.
If a us location is returned by the reverse geocoding engine the response will be contained within <usa> tags. For example:
Optionally the output may contain additional information the closest street corner as well as the closest major intersection - These responses will be held inside respectively <intersection> and <major_intersection> xml tags:
street1
The first street of the intersection.
A string
street2
The second street of the intersection.
A string
lattx
The latitude of the intersection.
A decimal number
longtx
The longitude of the intersection.
A decimal number
city
The city of the intersection.
A string
prov
The province of the intersection.
The two letter Canadian province code or US two letter state abbreviation.
distance
The distance of the intersection from the input location.
A decimal number expressed in kilometres
009
The latitude and longitude you provided are not in the valid range.
yy.yyy
-xx.xxx
A Simple Example:
#!/usr/bin/perl -w
#------------------------------------------------------------------#
#simple perl implementation api to the geocoder.ca xml server. #
#written by ervin ruci. #
#Requirements: #
# Perl Module : LWP. (from www.cpan.org) #
#also perl version 5.6.1 or greater is recomended but not required.#
#------------------------------------------------------------------#
use strict;
#these are the data that will be passed in as input
my $street_number = '101';
my $street_name = 'Wellington';
my $city = 'Ottawa';
my $province = 'ON';
my $postal = '';
my $id = 'req10001';
my $auth = '112078514150417x1'; #your authentication code for unthrottled access to the API
my %data; #this hash will hold the parsed output
my $url = "http://geocoder.ca" . "/?" . "stno=" . $street_number . "&addresst=" . $street_name . "&city="
. $city . "&prov=" . $province . "&postal=" . $postal . "&id=" . $id . "&geoit=XML" . "&auth=" . $auth;
use LWP::UserAgent;
my $ua = new LWP::UserAgent;
$ua->agent("ruci/0.1 " . $ua->agent);
my $req = new HTTP::Request('GET', $url);
$req->header(Subject => 'XML Get',
From => 'donotspam@goawayspamidiots.ca',
timeout => '3*10');
my $res = $ua->request($req);
if ($res->is_success) {
my $result = $res->content;
if ($result =~ /<latt>(.*)<\/latt>/) {
$data{latt} = $1;
}
if ($result =~ /<longt>(.*)<\/longt>/) {
$data{longt} = $1;
}
if ($result =~ /<id>(.*)<\/id>/) {
$data{id} = $1;
}
} else {
print "Error... The server said: " . $res->code . $res->message . "\n\n";
}
print "Got Latitude " . $data{latt} . "\n";
print "Got Longitude " . $data{longt} . "\n";
print "Additional Information " . $data{id} . "\n";
###################################################
######### That's It! ##############################
###################################################
Here is the output from this code:
Got Latitude 45.423361
Got Longitude -75.698537
Additional Information req10001
......................................
Here is another example illustrating a reverse geocoding client that uses the POST HTTP method
sub geocodercareverse {
my ($latt,$longt) = @_;
use LWP::UserAgent;
use HTTP::Request::Common;
my $ua = new LWP::UserAgent;
$ua->agent("ruci/0.1 " . $ua->agent);
my $res = $ua->request(POST 'http://geocoder.ca',
[
'latt' => $latt,
'longt' => $longt,
'geoit' => 'XML',
'auth' => '29876124912837723192x1',
'allna' => '1',
'reverse' => '1'
]
);
my ($ststn,$stadr,$stcity,$stprov,$szip);
if ($res->is_success) {
my $result = $res->content;
if ($result =~ /(.*)<\/uscity>/) {
$stcity = $1;
}
if ($result =~ /(.*)<\/state>/) {
$stprov = $1;
}
if ($result =~ /(.*)<\/usstnumber>/) {
$ststn = $1;
}
if ($result =~ /(.*)<\/usstaddress>/) {
$stadr = $1;
}
if ($result =~ /(.*)<\/zip>/) {
$szip = $1;
}
} else {
print STDERR "Error... The server said: " . $res->code . $res->message . "\n\n";
}
return ($ststn,$stadr,$stcity,$stprov,$szip);
}