telescope-net.com - GeocoderInfo

The telescope-net geocoder

This page describes the telescope-net geocoding service, and how to use it. It provides an introduction to using this API, and describes the parameters which can be included in requests.

What is geocoding anyway?

The process of "geocoding" is one by which an address or location is turned into latitude and longitude values. The resulting latitude and longitude values can be used for many purposes. Of specific interest here is using the result to establish an observer's location on the surface of the earth.

There are a number of other geocoding services in existence. See, for example, Google's geocoding service. None of these proved suitable for our purposes. For instance, Google's service requires that results from their geocoder be plotted on a map. This clearly doesn't fit with our astronomical use case, so we made one which better suits our purposes.

Limitations on usage

This service is primarily used by our Your moon google module. Locations can be specified in this module's configuration, in which case this geocoding service will be consulted to determine observing coordinates from that location name. This geocoding service is not heavily used at the moment, so please play nicely. If you intend to utilise this service in a serious way, please get in touch so that we may assess, and potentially adjust, service capacity.

You are free to use this service so long as the results are used for some astronomical or astronomy-related purpose.

Making requests

Requests sent to the geocoder should be of the following form:

http://www.telescope-net.com/apta/GEOCODER?parameters

Of the required parameters (address and latlng), you may specify only one.

address=address (required)
The address parameter in the request specifies to the location you wish to geocode. It can be the name of a city or a region, or the observatory code of an IAU/MPC observatory, or the name of a telescope-net observing site that is publicly available, or the name of a user-defined observing site that is publicly available. Only cities with populations of approximately 100000 people, or more, are currently in our database. As such, these are the only cities which will be returned.

latlng=latitude,longitude (required)
This type of request is often termed "reverse geocoding". Here, both latitude and longitude values are specified, and the names and details of observing sites are returned which lie close to the provided coordinates. As described above, the returned results may include cities, IAU/MPC observatories, telescope-net observing sites that is publicly available, and user-defined observing sites that is publicly available.

region=XX (optional)
By default, the results which are cities are biased towards the country of the requesting IP (this is similar to the behaviour of Google's geocoder). In other words, matching cities which lie in the same country as the requestor's IP address will appear first in the results list, with matching cities in other countries appearing further down. This behaviour can be overridden by specifying a region variable to the geocoder. The value of region should be a two-letter country code (formally an ISO 3166-1 code). You can also specify region=none to request no IP-based biasing of results. Note that results outside of the specified region are still returned, but they will appear lower down in the XML than results which lie within the specified region. The region parameter is intended to be used in conjunction with the address parameter. It doesn't make much sense to use region with a latlng request.

bounds=lat,lng|lat,lng (optional)
Geocoding requests can also specify a bounds parameter. The purpose of this is to preferentially favour the geocoding results which lie within a particular region. This region is specified as a "bounding box" in latitude and longitude. Because the world is complicated enough already, we have adopted the same format as is used by Google's geocoder. That is, the bounds value consists of two latitude and longitude pairs. These coordinates correspond to the southwest and northeast corners of the bounding box, and are separated by a pipe ("|") character. An example of a bounds specification which includes the Australian city of Brisbane is
```
bounds=-28.0,152.5|-27.0,153.5
```
Note that results outside of the bounds specification are still returned, but they will appear lower down in the XML than results which lie within the bounding region. Bounds specifications are intended to be used in conjunction with the address parameter. It doesn't make much sense to use bounds with a latlng request.

For all queries, the geocoder will respond with a maximum of ten entries. Cities will always be returned first in the results list, with other observing sites following.

We appreciate that many observatories, especially smaller observatories or those of private individuals, may not want their locations on the planet revealed to high accuracy. To that end, the administrators of individual observing sites can choose whether or not their observing site appears in the geocoder's results at all, and also whether or not the location should be "fuzzed". A "fuzzed" location will have latitude and longitude values modified such that they are somewhat inaccurate (up to 10 km). IAU/MPC observing sites are always "fuzzed" in this way, unless specifically requested otherwise by authorised individuals.

Geocoding example

Below is an example of a geocoder request, with an address value of "list":

http://www.telescope-net.com/apta/GEOCODER?address=list

The response is as follows:

<GeocodeResponse>
  <status>OK</status>
  <result>
    <type>locality</type>
    <siteid>BR_BragancaPaulista</siteid>
    <formatted_address>Braganca Paulista, BRAZIL</formatted_address>
    <gmtoffset_seconds>-10800</gmtoffset_seconds>
    <geometry>
      <location>
        <lat>-22.95194</lat>
        <lng>-46.54194</lng>
      </location>
    </geometry>
  </result>
  <result>
    <type>locality</type>
    <siteid>BR_Paulista</siteid>
    <formatted_address>Paulista, BRAZIL</formatted_address>
    <gmtoffset_seconds>-10800</gmtoffset_seconds>
    <geometry>
      <location>
        <lat>-7.94083</lat>
        <lng>-34.87306</lng>
      </location>
    </geometry>
  </result>
  <result>
    <type>locality</type>
    <siteid>BR_VarzeaPaulista</siteid>
    <formatted_address>Varzea Paulista, BRAZIL</formatted_address>
    <gmtoffset_seconds>-10800</gmtoffset_seconds>
    <geometry>
      <location>
        <lat>-23.21139</lat>
        <lng>-46.82833</lng>
      </location>
    </geometry>
  </result>
  <result>
    <type>locality</type>
    <siteid>RU_Elista</siteid>
    <formatted_address>Elista, RUSSIAN FEDERATION</formatted_address>
    <gmtoffset_seconds>14400</gmtoffset_seconds>
    <geometry>
      <location>
        <lat>46.30778</lat>
        <lng>44.25583</lng>
      </location>
    </geometry>
  </result>
  <result>
    <type>IAU/MPC observatory</type>
    <siteid>IAU_017</siteid>
    <formatted_address>Hoher List</formatted_address>
    <gmtoffset_seconds>7200</gmtoffset_seconds>
    <geometry>
      <location>
        <lat>50.13000</lat>
        <lng>6.87988</lng>
      </location>
    </geometry>
  </result>
</GeocodeResponse>

Let's make this request again, but this time add a bounds value which encompasses the observing site named Hoher List:

http://www.telescope-net.com/apta/GEOCODER?address=list&bounds=45,0|55,10

The response now has Hoher List as the first result.

<GeocodeResponse>
  <status>OK</status>
  <result>
    <type>IAU/MPC observatory</type>
    <siteid>IAU_017</siteid>
    <formatted_address>Hoher List</formatted_address>
    <gmtoffset_seconds>7200</gmtoffset_seconds>
    <geometry>
      <location>
        <lat>50.13000</lat>
        <lng>6.87988</lng>
      </location>
    </geometry>
  </result>
  <result>
    <type>locality</type>
    <siteid>BR_BragancaPaulista</siteid>
    <formatted_address>Braganca Paulista, BRAZIL</formatted_address>
    <gmtoffset_seconds>-10800</gmtoffset_seconds>
    <geometry>
      <location>
        <lat>-22.95194</lat>
        <lng>-46.54194</lng>
      </location>
    </geometry>
  </result>
  <result>
    <type>locality</type>
    <siteid>BR_Paulista</siteid>
    <formatted_address>Paulista, BRAZIL</formatted_address>
    <gmtoffset_seconds>-10800</gmtoffset_seconds>
    <geometry>
      <location>
        <lat>-7.94083</lat>
        <lng>-34.87306</lng>
      </location>
    </geometry>
  </result>
  <result>
    <type>locality</type>
    <siteid>BR_VarzeaPaulista</siteid>
    <formatted_address>Varzea Paulista, BRAZIL</formatted_address>
    <gmtoffset_seconds>-10800</gmtoffset_seconds>
    <geometry>
      <location>
        <lat>-23.21139</lat>
        <lng>-46.82833</lng>
      </location>
    </geometry>
  </result>
  <result>
    <type>locality</type>
    <siteid>RU_Elista</siteid>
    <formatted_address>Elista, RUSSIAN FEDERATION</formatted_address>
    <gmtoffset_seconds>14400</gmtoffset_seconds>
    <geometry>
      <location>
        <lat>46.30778</lat>
        <lng>44.25583</lng>
      </location>
    </geometry>
  </result>
</GeocodeResponse>

Reverse geocoding example

Below is an example of a reverse geocoder request, with a latlong value which is close to the observing site Hoher List:

http://www.telescope-net.com/apta/GEOCODER?latlng=50,7.0

The response is below. This lists a number of IAU/MPC observatories, along with some nearby cities (Koblenz, Bonn, Mainz, Wiesbaden and Trier). The results are typically in order of increasing distance from the coordinates provided in the request.

<GeocodeResponse>
  <status>OK</status>
  <result>
    <type>IAU/MPC observatory</type>
    <siteid>IAU_017</siteid>
    <formatted_address>Hoher List</formatted_address>
    <gmtoffset_seconds>7200</gmtoffset_seconds>
    <geometry>
      <location>
        <lat>50.13000</lat>
        <lng>6.87988</lng>
      </location>
    </geometry>
  </result>
  <result>
    <type>IAU/MPC observatory</type>
    <siteid>IAU_515</siteid>
    <formatted_address>Volkssternwarte Dhaun, near Kirn</formatted_address>
    <gmtoffset_seconds>7200</gmtoffset_seconds>
    <geometry>
      <location>
        <lat>49.77000</lat>
        <lng>7.52613</lng>
      </location>
    </geometry>
  </result>
  <result>
    <type>locality</type>
    <siteid>DE_Trier</siteid>
    <formatted_address>Trier, GERMANY</formatted_address>
    <gmtoffset_seconds>7200</gmtoffset_seconds>
    <geometry>
      <location>
        <lat>49.75565</lat>
        <lng>6.63935</lng>
      </location>
    </geometry>
  </result>
  <result>
    <type>locality</type>
    <siteid>DE_Koblenz</siteid>
    <formatted_address>Koblenz, GERMANY</formatted_address>
    <gmtoffset_seconds>7200</gmtoffset_seconds>
    <geometry>
      <location>
        <lat>50.35000</lat>
        <lng>7.60000</lng>
      </location>
    </geometry>
  </result>
  <result>
    <type>IAU/MPC observatory</type>
    <siteid>IAU_196</siteid>
    <formatted_address>Homburg-Erbach</formatted_address>
    <gmtoffset_seconds>7200</gmtoffset_seconds>
    <geometry>
      <location>
        <lat>49.32000</lat>
        <lng>7.31315</lng>
      </location>
    </geometry>
  </result>
  <result>
    <type>locality</type>
    <siteid>DE_Bonn</siteid>
    <formatted_address>Bonn, GERMANY</formatted_address>
    <gmtoffset_seconds>7200</gmtoffset_seconds>
    <geometry>
      <location>
        <lat>50.73333</lat>
        <lng>7.10000</lng>
      </location>
    </geometry>
  </result>
  <result>
    <type>IAU/MPC observatory</type>
    <siteid>IAU_090</siteid>
    <formatted_address>Mainz</formatted_address>
    <gmtoffset_seconds>7200</gmtoffset_seconds>
    <geometry>
      <location>
        <lat>49.95000</lat>
        <lng>8.24534</lng>
      </location>
    </geometry>
  </result>
  <result>
    <type>locality</type>
    <siteid>DE_Wiesbaden</siteid>
    <formatted_address>Wiesbaden, GERMANY</formatted_address>
    <gmtoffset_seconds>7200</gmtoffset_seconds>
    <geometry>
      <location>
        <lat>50.08333</lat>
        <lng>8.25000</lng>
      </location>
    </geometry>
  </result>
  <result>
    <type>IAU/MPC observatory</type>
    <siteid>IAU_023</siteid>
    <formatted_address>Wiesbaden</formatted_address>
    <gmtoffset_seconds>7200</gmtoffset_seconds>
    <geometry>
      <location>
        <lat>50.04000</lat>
        <lng>8.26781</lng>
      </location>
    </geometry>
  </result>
  <result>
    <type>locality</type>
    <siteid>DE_Mainz</siteid>
    <formatted_address>Mainz, GERMANY</formatted_address>
    <gmtoffset_seconds>7200</gmtoffset_seconds>
    <geometry>
      <location>
        <lat>50.00000</lat>
        <lng>8.27111</lng>
      </location>
    </geometry>
  </result>
</GeocodeResponse>