iBegin Geocoder Documentation
You can get your API key from your account page.
Contents:
Queries
All queries to the iBegin Geocoder are to be done to http://geocoder.ibegin.com/geoxml/ using GET method. The response will be in XML.
Each section gives example queries and responses.
You must have a valid API key to be able to do a query. You can get your API key from your account page.
Intelligent Parser
The intelligent parser can perform forward geocoding or street intersections. It reads the query line, parses out the pertinent information, and then returns a response. Simply provide it with an address you would give to someone else, and it will try to decode it.
Input Parameters (via GET method)
| Parameter Name |
Description |
Restrictions |
| apikey |
API key for your domain |
- |
| location |
Location that you are attempting to geocode. |
Must contain street number, street address, and city. It must also include state/province (two letter code) and/or ZIP/Postal Code, but providing both is better for accuracy. In the case of only geocoding a ZIP/Postal Code, only that value is required. |
| id (optional) |
You can provide a transaction id for your own record-keeping purposes |
String no longer than 250 characters |
Output Values
Since the intelligent parser can do both forward geocoding and street intersections, please see those two sections for specific output values.
Examples:
Geocoding '200 Elm Street, Toronto, ON':
Query:
http://geocoder.ibegin.com/geoxml/?apikey=XXXXXXXXX&location=200+Elm+Street,+Toronto,+ON
Response:
Geocoding '90210' with id '2352342':
Query:
http://geocoder.ibegin.com/geoxml/?apikey=XXXXXXXXX&location=90210&id=2352342
Response:
Geocoding 'Yonge and Bloor, Toronto':
Query:
http://geocoder.ibegin.com/geoxml/?apikey=XXXXXXXXX&location=yonge+and+bloor,+toronto
Response:
Forward Geocoding
Input Parameters (via GET method)
| Parameter Name |
Description |
Restrictions |
| apikey |
API key for your domain |
- |
| staddress |
Street address |
String not longer than 200 characters |
| stcity |
City |
String not longer than 200 characters |
| ststate |
State / Province |
Must be in two letter format (eg TX for Texas or ON for Ontario) |
| stzip |
ZIP/ Postal Code |
Must be either 5 digit ZIP or 6 character Postal Code |
| standardize (optional) |
Returns the 'properly standardized' address |
One allowed value: 1 |
| id (optional) |
You can provide a transaction id for your own record-keeping purposes |
String no longer than 250 characters |
Output Values
| Parameter Name |
Description |
Expected Value |
| latitude |
Latitude |
Decimal with six significant digits |
| longitude |
Longitude |
Decimal with six significant digits |
| zip |
ZIP / Postal Code |
5 digit (ZIP) or 6 characters (postal code) |
| id (optional) |
id value provided by end user |
- |
If you set standardize=1, you will get the standardized information in <standardized>:
| Parameter Name |
Description |
Expected Value |
| stnumber |
Street address number |
PLEASE NOTE: Street number and name are separate in this response |
| stname |
Street address name |
- |
| stcity |
City |
- |
| ststate |
State / Province |
Will be in two letter format (eg NY for New York or BC for British Columbia) |
Examples:
Geocoding '1600 Pennsylvania Avenue NW, Washington, DC':
Query:
http://geocoder.ibegin.com/geoxml/?apikey=XXXXXXXXX&staddress=1600+Pennsylvania+Avenue+NW&stcity=Washington&ststate=DC&stzip=
Response:
Geocoding '1600 Pennsylvania Avenue NW, Washington, DC' with 'standardize=1':
Query:
http://geocoder.ibegin.com/geoxml/?apikey=XXXXXXXXX&staddress=1600+Pennsylvania+Avenue+NW&stcity=Washington&ststate=DC&stzip=&standardize=1
Response:
Reverse Geocoding
Input Parameters (via GET method)
| Parameter Name |
Description |
Restrictions |
| apikey |
API key for your domain |
- |
| latitude |
Latitude |
- |
| longitude |
Longitude |
- |
| cross (optional) |
If used, also returns nearest intersection and nearest major intersection |
One allowed value: 1 |
| id (optional) |
You can provide a transaction id for your own record-keeping purposes |
String no longer than 250 characters |
Output Values
| Parameter Name |
Description |
Expected Value |
| latitude |
Latitude of geocoded address |
Decimal with six significant digits |
| longitude |
Longitude of geocoded address |
Decimal with six significant digits |
| stnumber |
Street number |
- |
| stname |
Street address name |
- |
| stcity |
City |
- |
| ststate |
State / Province |
Will be in two letter format (eg NY for New York or BC for British Columbia) |
| stzip |
ZIP/ Postal Code |
5 digit (ZIP) or 6 characters (postal code) |
| inputlatitude |
Latitude queried |
- |
| inputlongitude |
Longitude queried |
- |
| distance |
Distance between latitude/longitude specified and this intersection |
Will be in kilometers |
| id (optional) |
id value provided by end user |
- |
If you set cross=1, you will get the nearest intersection (in <intersection>) and major intersection (in <major_intersection>) results. Please note that this will slightly degrade the response time.
Output Values
| Parameter Name |
Description |
Expected Value |
| street1 |
First street of intersection |
- |
| street2 |
Second street of intersection |
- |
| latitude |
Latitude of intersection |
Decimal with six significant digits |
| longitude |
Longitude of intersection |
Decimal with six significant digits |
| stcity |
City |
- |
| ststate |
State / Province |
- |
| distance |
Distance between latitude/longitude specified and this intersection |
Will be in kilometers |
Examples:
Reverse geocoding '38.898748,77.037684':
Query:
http://geocoder.ibegin.com/geoxml/?apikey=XXXXXXXXX&latitude=38.898748&longitude=-77.037684
Response:
Reverse geocoding '38.898748,77.037684' with 'cross=1':
Query:
http://geocoder.ibegin.com/geoxml/?apikey=XXXXXXXXX&latitude=38.898748&longitude=-77.037684&cross=1
Response:
Street Intersection
Input Parameters (via GET method)
| Parameter Name |
Description |
Restrictions |
| apikey |
API key for your domain |
- |
| street1 |
Street 1 |
String not longer than 200 characters |
| street2 |
Street 2 |
String not longer than 200 characters |
| stcity |
City |
String not longer than 200 characters |
| ststate |
State / Province |
Must be in two letter format (eg TX for Texas or ON for Ontario) |
| stzip |
ZIP/ Postal Code |
Must be either 5 digit ZIP or 6 character Postal Code |
| id (optional) |
You can provide a transaction id for your own record-keeping purposes |
String no longer than 250 characters |
Output Values
| Parameter Name |
Description |
Expected Value |
| latitude |
Latitude |
Decimal with six significant digits |
| longitude |
Longitude |
Decimal with six significant digits |
| id (optional) |
id value provided by end user |
- |
Street intersection for 'Sunset Boulevard' and 'Elysian Park' in 'Los Angeles, CA':
Query:
http://geocoder.ibegin.com/geoxml/?apikey=XXXXXXXXX&street1=Sunset+Boulevard&street2=Elysian+Park+Avenue&stcity=Los+Angeles&ststate=CA&stzip=
Response:
Reverse geocoding '38.898748,77.037684' with 'cross=1':
Query:
http://geocoder.ibegin.com/geoxml/?apikey=XXXXXXXXX&street1=Hurontario&street2=Brittania&stcity=Mississauga&ststate=ON&stzip=&id=5x1a
Response:
Suggestions
Sometimes when unable to find an address, we may respond with a suggestion. The format of the response (found within <suggestion>) will be:
Forward Geocoding
| Parameter Name |
Description |
Expected Value |
| stnumber |
Street address number |
PLEASE NOTE: Street number and name are separate in this response |
| stname |
Street address name |
- |
| stcity |
City |
- |
| ststate |
State / Province |
Will be in two letter format (eg NY for New York or BC for British Columbia) |
Geocoding for '400 Elm Street, Toronto, ON':
Query:
http://geocoder.ibegin.com/geoxml/?apikey=XXXXXXXXX&location=400+Elm+Street,+Toronto,+ON
Response:
Geocoding for '400 Rosinante Road, El Paso, TX':
Query:
http://geocoder.ibegin.com/geoxml/?apikey=XXXXXXXXX&staddress=400+rosinante+road&stcity=el+paso&ststate=tx&stzip=
Response:
Intersection
| Parameter Name |
Description |
Expected Value |
| suggstreet1 |
Suggested street 1 |
- |
| suggstreet2 |
Suggested street 2 |
- |
| stcity |
Suggested city |
- |
| ststate |
Suggested state |
Will be in two letter format (eg NY for New York or BC for British Columbia) |
Error Responses
There are two kinds of errors - base errors and geocoding errors.
Base Errors
- Your API key has been locked - if a commercial user, you have ran out of credits. If a non-commercial, you have reached your daily limit of 100. As a buffer, we allow commercial users to over-run to -100.
- Invalid API Key - self-explanatory, the API key you are attempting to use is invalid. Please visit your account page to get your API key.
- This IP is not allowed to use this API Key - also self-explanatory, the IP attempting to retrieve the results is not one of the IPs currently specified in your account.
Example:
Geocoding Errors
In situations where the geocoding system cannot yield an answer, an error description will be returned. There are three possible errors:
- Invalid query - the system was unable to make sense of what was being queried.
- Your query did not produce any results - the system was not able to return a specific answer. It may have a suggestion.
- Unable to understand that query - misc error. In such a case best to contact us.
PLEASE NOTE: If we are unable to successfully geocode your request, you are
not charged.
Example:
