Main Page

From wiki.coolgeo.org
Jump to navigation Jump to search

XML Interface Description for Coolgeo.org and Mailheader.org.

This is about the coolgeo.org website along with the API interface for universal usage. Coolgeo.org offers an easy XML API to to query geo and station data
The XML API is also used by mailheader.org

About Coolgeo.org


Coolgeo is using Maxdata to resolve IPv4 and IPv6 addresses into geographic coordinates.
Coolgeo knows more than 25.000 Worldwide Codes (Stations), the stations are divided into subcodes such as city or airport codes.
Each code has its timezone and geographic coordinates associated (latitude/longitude) and knows also the timezone, currency, DST and other data.

Rules and notations

  • All geo data values are set or given in decimal values.
  • Date and Time is always returned within the local timezone unless specified else.
  • Values are returned in upper cases.
  • Distances are always set in kilometer.
  • Times are always given in a 24 hour format.



Codes
IATA Codes are used for station data, please get more information here

  • A = Airport
  • B = Bus Station
  • C = City
  • G = Ground Data
  • H = Heli Port
  • R = Railway Station

URL Sites via WUI

URL Sites via XML


Return your current IP

Return your current IP

Sample: http://xml.coolgeo.org/xml.cgi?getip=1
Enforce IPv4 Sample: http://v4.xml.coolgeo.org/xml.cgi?getip=1
Enforce IPv6 Sample: http://v6.xml.coolgeo.org/xml.cgi?getip=1


Return example

<Client IP="2003:c0:xxxx:xxxx::0"/>

Search location by a IP address

Search location by a IP address

IPv4 Sample: http://xml.coolgeo.org/xml.cgi?ip=1.2.3.4&optASN&optTZData&optStation&optAirport
IPv6 Sample: http://xml.coolgeo.org/xml.cgi?ip=2604%3Aa880%3A0%3A1010%3A%3A809%3Ac001&optASN&optTZData&optStation&optAirport



Options:

  • optASN Give ASN data
  • optTZData Give TZ data
  • optStation Give station data
  • optAirport Give airport data



Return example for search ip=1.2.3.4

<Status>
 <Search IPAddress="1.2.3.4" Search="ipdata" optASN="1" optTZData="1" optStation="1" optAirport="1"/>
 <Response>
  <Ip 
   Latitude="47.9130" 
   Longitude="-122.3042" 
   CountryCode="US" 
   CountryName="UNITED STATES" 
   CurrencyCode="USD" 
   CurrencyName="US DOLLAR"
   IsAnonProxy="0" 
   AccuracyRadius="100"/>
  />
  <Asn 
   Name="Google Inc." 
   Number="AS15169"
  />
  <TZ 
   Code="America/Los_Angeles" 
   Offset="-28800" OffsetRnd="-8" 
   CurrentEpoch="1451556331" 
   CurrentEpochGMT="82" 
   CurrentDate="Thu Dec 31 11:05:31 2015" 
   ShortName="PST" isDST="0"
  />
  <NearestStation 
   Code="PAE" 
   Type="A" 
   Name="Snohomish Cty Arpt" 
   City="Everett" 
   Distance="2"
  />
  <NearestAirport 
   Code="LKE" 
   Type="A" 
   Name="Lake Union Seaplane Base" 
   City="Seattle" 
   Distance="14"
  />
 </Response>
</Status>

Search location by a argument

Search location by a string, this could be any meaning, a city, code or country name to be matched

Search for Juneau, no matter what station code.
Sample: http://xml.coolgeo.org/xml.cgi?search=location&value=Juneau

Return example for search=location, value=Juneau

<Status>
 <ResponseArray>
  <Response>
   <Count>1</Count>
   <Code>JNU</Code>
   <Type>A</Type>
   <Name>Juneau Arpt</Name>
   <CityCode>JNU</CityCode>
   <CityName>Juneau</CityName>
   <CountryCode>US</CountryCode>
   <CountryName>UNITED STATES</CountryName>
   <StateCode>AK</StateCode>
   <StateName>ALASKA</StateName>
   <Latitude>+058.3590</Latitude>
   <Longitude>-134.5652</Longitude>
  </Response>
  <Response>
   <Count>2</Count>
   <Code>JNU</Code>
   <Type>C</Type>
   <Name>Juneau</Name>
   <CityCode>JNU</CityCode>
   <CityName>Juneau</CityName>
   <CountryCode>US</CountryCode>
   <CountryName>UNITED STATES</CountryName>
   <StateCode>AK</StateCode>
   <StateName>ALASKA</StateName>
   <Latitude>+058.3000</Latitude>
   <Longitude>-134.4056</Longitude>
  </Response>
  <Response>
   <Count>3</Count>
   <Code>UNC</Code>
   <Type>A</Type>
   <Name>Dodge County Airport</Name>
   <CityCode>UNU</CityCode>
   <CityName>Juneau</CityName>
   <CountryCode>US</CountryCode>
   <CountryName>UNITED STATES</CountryName>
   <StateCode>WI</StateCode>
   <Latitude>+058.3000</Latitude>
   <Longitude>-134.4167</Longitude>
  </Response>
 </ResponseArray>
<Search Mode="location" Value="Juneau" Found="3"/>
</Status>

Search location details by latitude and longitude

Show details by latitude and longitude is about to return data such as the nearest city, airport, localtime and others.

Sample: http://xml.coolgeo.org/xml.cgi?show=geo&latitude=+37.78848&longitude=-122.3750

Return example for show=geo, latitude=+37.7884, longitude=-122.3750

<Status>
 <Response>
  <TZ 
   Code="America/Los_Angeles" 
   Offset="-28800" OffsetRnd="-8" 
   CurrentEpoch="0000000000" 
   CurrentEpochGMT="0000000000" 
   CurrentDate="DDD MMM DD HH:MM:SS YYYY" 
   CurrentDateGMT="DDD MMM DD HH:MM:SS YYYY" 
   ShortName="PST" 
   isDST="0"
  />
  <NearestStation 
   Code="SFO" 
   Type="C" 
   Name="San Francisco" 
   City="San Francisco" 
   Distance="2" 
   CountryCode="US" 
   CountryName="UNITED STATES"
  />
  <NearestAirport 
   Code="OAK" 
   Type="A" 
   Name="Metro Oakland Intl Arpt" 
   City="Oakland" 
   Distance="16" 
   CountryCode="US" 
   CountryName="UNITED STATES"
  />
 </Response>
</Status>


Search station details by code

Show details by Code and return data such as lat, lon, name details, currency, time and others.

Sample: http://xml.coolgeo.org/xml.cgi?show=location&value=syd&type=c

Return example for show=location, value=syd (Sydney) and type=c (Ciity Code)

<Response 
 Code="SYD" 
 Type="C" 
 Name="Sydney" 
 CityCode="SYD" 
 CityName="Sydney" 
 StateCode="NS" 
 StateName="New South Wales" 
 CountryCode="AU" 
 CountryName="AUSTRALIA" 
 ContinentCode="OC" 
 ContinentName="Oceania" 
 Longitude="+151.2062" 
 Latitude="-033.8705" 
 TZCode="AEDT" 
 TZName="Australia/Sydney" 
 Offset="39600" 
 OffsetRnd="+11" 
 CurrentEpoch="0000000000" 
 CurrentDate="DDD MMM DD HH:MM:SS YYYY" 
 isDST="1" 
 CurrencyCode="AUD" 
 CurrencyName="Australian Dollar"
/>


Radius search

By City or Airport

Show cities by radius search

Display stations (using the CityCode in this example) by radius distance, use km as unit, the max distance is 500KM, stations can be a city, airport and other station codes.
Optional request is possible by airport code (type=A) or geo data (type=G).
This example runs by airport as reference point.
Show cities around the airport of Edinborough (EDI)in a 100KM radius distance.

Sample: http://xml.coolgeo.org/xml.cgi?show=radius&type=A&value=EDI&srctype=A&radius=100&dsttype=C&recent=1



This return example shows the status header and the return data as an array.
In case of a airport search the geo data will be determined and used as a reference for the radius calculation, this data is shown in the below as Latitude/Longitude.

Return status:

<Search 
 Type="A" 
 SourceType="A" 
 DestinationType="C" 
 Value="EDI" 
 Latitude="+055.9480" 
 Longitude="-003.3642" 
 Radius="100" 
 Recent="1"
/>


Reponse sample, note that his is a array, the count id is used as reference.
The array is sorted by distance (km away of the reference point), sort order is ascent.

<Response 
 Code="XWB"
 Count="2" 
 Distance="40" 
 Name="Stirling" 
 Type="C" 
 Latitude="+056.1181" 
 Longitude="-003.9383"
 CountryCode="GB"
 CountryName="UNITED KINGDOM"
/>

Show airports by radius search

Display stations (using the AiprotCode in this example) by radius distance, use km as unit, the max distance is 500KM, stations can be a city, airport and other station codes.
Optional request is possible by airport code (type=A) or geo data (type=G).
This example runs by airport as reference point, return should be airports (dsttype=A).
Show airports around the airport of San Francisco (SFO) in a 100KM radius distance.

Sample: http://xml.coolgeo.org/xml.cgi?show=radius&type=A&value=SFO&srctype=A&radius=100&dsttype=A&recent=1



This return example shows the status header and the return data as an array.
In case of a airport search the geo data will be determined and used as a reference for the radius calculation, this data is shown in the below as Latitude/Longitude.

Return status:

<Search 
 Type="A" 
 SourceType="A"
 DestinationType="A"
 Value="SFO"
 Longitude="-122.3819"
 Latitude="+037.6183"
 Radius="100" 
 Recent="1"
/>


Reponse sample, note that this is an array, the count id is used as reference.
The array is sorted by distance (km away of the reference point), show type=cities, sort order is ascent.

<Response 
 Code="XWB"
 Count="2" 
 Distance="40" 
 Name="Stirling" 
 Type="C" 
 Latitude="+056.1181" 
 Longitude="-003.9383"
 CountryCode="GB"
 CountryName="UNITED KINGDOM"
/>


By Geo Data

Show cities by radius search

Display any stations (using the Geo Data in this example) by radius distance, use km as unit, the max distance is 500KM, use latitude and longitude as parameter
This example runs by geo data as reference point
return should be any ( no usage of dsttype).
Show cities around the data latitude=+40.7528 and longitude=-73.9757 (NYC), 100KM radius distance.

Sample: http://xml.coolgeo.org/xml.cgi?show=radius&type=G&latitude=+40.7528&longitude=-73.9757&radius=100&dsttype=A&recent=1



This return example shows the status header and the return data as an array.
In case of a airport search the geo data will be determined and used as a reference for the radius calculation, this data is shown in the below as Latitude/Longitude.

Return status:

<Search
 Type="G"
 SourceType=""
 DestinationType="C"
 Value=""
 Longitude="-73.9757"
 Latitude=" 40.7528"
 Radius="100"
 Recent="1"
/>

Reponse sample, note that this is an array, the count id is used as reference.
The array is sorted by distance (km away of the reference point), show type=cities, sort order is ascent.

<Response
 Code="NYC"
 Count="1"
 Distance="0"
 Name="New York"
 Type="C"
 Latitude="+040.7528"
 Longitude="-073.9757"
 CountryCode="US"
 CountryName="UNITED STATES"
/>


Show any stations by radius search

Display stations (using the Geo Data in this example) by radius distance, use km as unit, the max distance is 500KM, use latitude and longitude as parameter
Optional request is possible by airport code (type=A) or geo data (type=G).
This example runs by geo data as reference point
Show any stations around the data latitude=+61.1 and longitude=-45.1 (Somewhere in Greenland), 500KM radius distance.

Sample: http://xml.coolgeo.org/xml.cgi?show=radius&type=G&latitude=+61.1&longitude=-45.1&radius=500&recent=1



This return example shows the status header and the return data as an array.
In case of a airport search the geo data will be determined and used as a reference for the radius calculation, this data is shown in the below as Latitude/Longitude.

Return status:

<Search
 Type="G"
 SourceType=""
 DestinationType=""
 Value="" 
 Longitude="-45.1"
 Latitude=" 61.1"
 Radius="500"
 Recent="1"
/>


Reponse sample, note that this is an array, the count id is used as reference.
The array is sorted by distance (km away of the reference point), show type=cities, sort order is ascent.

<Response
 Code="UAK"
 Count="1"
 Distance="13"
 Name="Narsarsuaq"
 Type="C"
 Latitude="+061.1667"
 Longitude="-045.3167"
 CountryCode="GL"
 CountryName="GREENLAND"
/>


Distance search

By Latitude / Longitude

Example for Winnipeg to Sydney

  • Winnipeg: srclat=+49.9033&srclon=-97.2262
  • Sydney: dstlat=-33.9377&dstlon=+151.1648
http://xml.coolgeo.org/xml.cgi?show=distance&srclat=+49.9033&srclon=-97.2262&dstlat=-33.9377&dstlon=+151.1648

Response Sample:

<Status>
 <Response>
  <DistanceMile>8879.11</DistanceMile>
  <DistanceKilometer>14289.54</DistanceKilometer>
 </Response>
 <Search 
  Show="distance" 
  Source_Latitude=" 49.9033" 
  Source_Longitude="-97.2262" 
  Destination_Latitude="-33.9377" 
  Destination_Longitude=" 151.1648"
 />
</Status>

Timezone

Timezone and UTC information by airport or city code and datetime

This function is showing the current timezone along with the UTC epoch, UTC datetime and daylight saving information.

Fro example: Show the local Timezone and UTC datetime information for San Francisco - 4th of July 2025, 12:30 PM

http://xml.coolgeo.org/xml.cgi?show=tzinfo&code=SFO&date=20250704&time=123000

Response Sample:

<Status>
 <Response>
  <LocationCity>San Francisco</LocationCity>
  <LocationTZ>America/Los_Angeles</LocationTZ>
  <LocationTZAbbr>PDT</LocationTZAbbr>
  <Offset>-7</Offset>
  <OffsetSeconds>-25200</OffsetSeconds>
  <LocalEpoch>1751606580</LocalEpoch>
  <UTCDate>2025-07-04 05:30:00</UTCDate>
  <UTCEpoch>1751607000</UTCEpoch>
  <isDST>1</isDST>
  <hasDST>1</hasDST>
 </Response>
 <Search Code="SFO" Date="20250704" Time="123000"/>
</Status>