About This Service

This service powers certain features of certain Netsyms applications. You can use it too.
You can request results as a JSON array or as easily-processed plaintext (in case your app doesn't have a JSON library). For JSON, simply send the GET argument "format=json".

In plaintext mode, if the response is non-zero in length and does not start with "OK", you can assume it is a human-readable error message suitable for display.

In JSON mode, if the status is not "OK" you can assume it is an error message.

You can request this API with HTTPS, thanks to Let's Encrypt.


Places Database

This API allows you to find places near a set of coordinates in the United States.

It uses data from the OpenStreetMap project, and this data is licensed from there.

This API only fully supports JSON and GeoJSON output (use format=geojson).

Parameters:
format=json OR geojson      Output format
lat=[latitide]              Latitude, required
long=[longitude]            Longitude, required
radius=5                    Search radius in miles (default 5)
names=0                     Filter to places with names if 1 (default 0)
                

Sample Query:

https://earth.apis.netsyms.net/places.php?format=geojson&lat=46.5997&long=-112.0379&radius=.1&names=1
                

Response:

{
  "name":"Places",
  "type":"FeatureCollection",
  "features":[
    {
      "type":"Feature",
      "geometry":{
        "type":"Point",
        "coordinates":[
          -112.03658,
          46.59854
        ]
      },
      "properties":{
        "osm_id":96962979,
        "name":"KTVH",
        "name:en":"KTVH",
        "amenity":"studio",
        "historic":null,
        "tourism":null
      }
    },
    {
      "type":"Feature",
      "geometry":{
        "type":"Point",
        "coordinates":[
          -112.03853,
          46.60038
        ]
      },
      "properties":{
        "osm_id":357981049,
        "name":"Saint Charles Chapel",
        "name:en":"Saint Charles Chapel",
        "amenity":"place_of_worship",
        "historic":null,
        "tourism":null
      }
    },
    {
      "type":"Feature",
      "geometry":{
        "type":"Point",
        "coordinates":[
          -112.03917,
          46.59981
        ]
      },
      "properties":{
        "osm_id":357981051,
        "name":"Borromeo Chapel",
        "name:en":"Borromeo Chapel",
        "amenity":"place_of_worship",
        "historic":null,
        "tourism":null
      }
    }
  ]
}
                

Terrain Information

This service pulls terrain data from the National Land Cover Database 2011 (NLCD 2011).

It returns data based on the legend found here.

You must send coordinates with at least four decimal places; any less and your request will be denied with an error message. Extra precision will be ignored due to the resolution of the source data.

This API does not function outside the USA; if you attempt to fetch data that is not in this dataset, it will return a typeid of 0.

Parameters:
format=json                 Output format (default none, plain text)
lat=[latitide]              Latitude, required
long=[longitude]            Longitude, required
                

Sample Query:

http://earth.apis.netsyms.net/terrain.php?lat=45.5172&long=-112.1211
                

Sample Response:

OK:42|eforest|areas dominated by trees generally greater than 5 meters tall...
                


Query with JSON output:

http://earth.apis.netsyms.net/terrain.php?lat=45.5172&long=-112.1211&format=json
                

Response:

{"typeid":42,"typename":"eforest","typedesc":"areas dominated by trees generally greater...","status":"OK"}
                

Sample Errors:

http://earth.apis.netsyms.net/terrain.php?lat=45.51&long=-112.1211
Error: Latitude (lat) is in the wrong format, or does not have enough precision...

http://earth.apis.netsyms.net/terrain.php?lat=45.51&long=-112.1211&format=json
{ "status": "ERROR", "message": "Latitude (lat) is in the wrong format...)" }
                

Weather Information

This weather API is Powered by Forecast.

This API costs us 10 cents for every 1000 queries you run, so be respectful or just use our source directly at developer.forecast.io. Their API is really nice too, and provides a lot more information.

Because these APIs are USA-centric, temperatures are in Fahrenheit. Yes, I know.

Weather data for a particular coordinate pair is cached for an hour and not re-requested from Forecast.io until it expires from the cache.

This API requires two decimal places of precision. Any less will throw an error, any more will be ignored.

For info on the "icon" property, go to this page.

Parameters:
format=json                 Output format (default none, plain text)
lat=[latitide]              Latitude, required
long=[longitude]            Longitude, required
                

Sample Query:

http://earth.apis.netsyms.net/weather.php?lat=45.51&long=-112.12
                

Sample Response:

OK:27.9|cloudy
                


Query with JSON output:

http://earth.apis.netsyms.net/weather.php?lat=45.51&long=-112.12&format=json
                

Response:

{"temp":"27.9","icon":"cloudy","status":"OK"}