Throttled XML API for not-for-profits. (Cost: free)

We throttle {rate limit} requests to our free XML port up to a maximum number of lookups per request source per day. If you are a non for profit entity and this limit if too low for your needs, send us a note at geodata { at } geocoder [dot] ca, and we will determine wether to raise your limits on a case by case basis. (you will also need a static ip address)

Otherwise you may want to look at our unthrottled XML port. where lookups are limited to the number of lookup credits obtained.

Also note that the limits on the free XML port are dynamically assigned. If our server load goes up, the limit becomes more restrictive and vice versa. Normally it will be in the range of 500-2000 lookups per day.

(entities using this port must be not-for-profit and provide an acknowledgement. See our Terms of Service for more details.)

Geocoder.ca provides real-time geocoding for your application via a simple XML interface.

Geocoding API : Reverse Geocoding API : Cross Street Intersection Geocoding API - [User supplied coding and documentation material]

Specifications: (Same as the commercial api with exclusion of the "auth" parameter) Input

The following parameters must be sent to http://geocoder.ca using either a GET or POST HTTP method.

Parameter Name DescriptionPermitted Values
addresst The name of the street address. A string no longer that 220 bytes.
stno Street Number A number.
city The City Name A sting no longer that 220 bytes.
prov The Two letter Canadian province code. (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)
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.
recompute Optionally specified for better accuracy. (manual verification shows that this method produces a "slightly" more accurate response 60% of the time, and a "slightly" less accurate response 40% of the time). It is slower and more cpu intensive on our end that is why we do not make it the default. 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 a valid location entity. The parameter geoit=XML is also required.


Output

The output will contain a maximum of three parameters in an XML format.

Parameter Name DescriptionExpected Output Values
latt The latitude. A decimal number.
longt The longitude. A decimal number.
id Transaction id. If supplied in the input the transaction id will be returned along with the output.


Error Codes: The output could contain an error code. If your query does not produce coordinates the latt longt containers will be empty.
These are some possible error codes:

005 Postal Code is not in the proper Format.

004 Specify a Canadian province two letter code.

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>

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:
http://geocoder.ca/?stno=12&addresst=prince+of+whalas&city=ottawa&prov=ON&geoit=xml&topmatches=5

006 We currently throttle, rate limit, requests to our free XML port to a maximum of $daily_max lookups per request source per day to ensure fair and equal access to our services. If you need this limit raised for your not-for-profit entity contact us. Please note that the daily maximum is set dynamically depending on the server load for that moment.


Cross Street geocoding involves finding the coordinates of the point where two given streets intersect.
Cross Street Intersection Geocoding Specifications: Input

The following parameters must be sent to http://geocoder.ca using either a GET or POST HTTP method.

Allowed values are Integer 0 or 1.
Parameter Name DescriptionPermitted Values
street1 The name of the first street A sting no longer that 220 bytes.
street2 The name of the second street A sting no longer that 220 bytes.
city The City Name A sting no longer that 220 bytes.
prov The Two letter Canadian province code. (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
Suggestion System:

Sometimes a suggestion will be provided upon an unsucessful request.

for example:
<suggestion>
<suggstreet1>MEADOWLANDS DR E</suggstreet1>
<suggstreet2>PRINCE OF WALES DR </suggstreet2>
<city>nepean</city>
<prov>ON</prov>
</suggestion>


Reverse geocoding is the process whereupon you supply a latitude-longitude pair and get the closest street address to this pair.
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 DescriptionPermitted Values
latt The Latitude. A decimal number.
longt The Longitude. A decimal number.
range The optional range to limit the reverse geocoding. A number.
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 DescriptionExpected 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.
Optionally the output may contain additional information about a nearby street corner:
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.
distance The distance of the intersection from the input location. A decimal number expressed in kilometres



A Simple Perl Example: Click here for a php example | another php example

This is a simple interface to the geocoder.ca API written in perl.

#!/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 %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";
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