t
The aprs.fi API (Application Programming Interface) allows application developers to query the aprs.fi database from their own web applications. To use the API you need to sign up for an user account on aprs.fi - your API key can be found in the account settings (My account).
Terms:
User-Agent: findlinks/1.1.6-beta1 (+http://wortschatz.uni-leipzig.de/findlinks/)The API is supposed to be used for developing applications which add value to the data collected by aprs.fi. It may not be used to simply copy all of the data to another site providing exactly the same features as aprs.fi. If you wish to set up a clone site, please collect your data directly from the APRS-IS - it's easy to parse using Ham::APRS::FAP.
The API limits the rate of requests to a sensible level, which can be adjusted if needed. The limits are designed to protect aprs.fi from too heavy load, and to protect the database contents from harvesting. If your application hits the limits and you'd like to have a larger quota, please get in touch and describe your application's needs in detail.
Most requests should normally be served within tens of milliseconds, since they do not usually require any disk access. In any case, you should write your application so that it will time out requests in a few seconds. If multiple requests fail in a row, your application should assume that the service is not available and slow down the rate of attempts using an exponential backoff algorithm.
The API returns data in either JSON or XML format, JSON being the default and recommended format since it has much smaller overhead when compared to XML. XML responses can be easily twice as large as the equivalent JSON responses. See json.org for parsing instructions. If you're programming in PHP, json_decode is your friend.
This document lists all the API calls available. If a function is not listed here, it is not there; unfortunately there are not hidden gems to be found.
Basic location query using JSON:
Whitespace and indentation has been added to the response to increase readability in this document.
Timestamps are returned in the Unix time format. All other variables are returned in metric units, where applicable. Speed is measured in kilometers per hour, altitude in meters, temperature in degrees Celsius. Latitude and Longitude are given in decimal degrees, positive values being north for latitude and east for longitude. The responses only contain keys for data which is known.
Please note that this API is for querying specific stations. It intentionally does not support searching by wildcard.
https://api.aprs.fi/api/get?name=OH7RDA&what=loc&apikey=APIKEY&format=json
{
"command":"get",
"result":"ok",
"what":"loc",
"found":1,
"entries": [
{
"name":"OH7RDA",
"type":"l",
"time":"1267445689",
"lasttime":"1270580127",
"lat":"63.06717",
"lng":"27.66050",
"symbol":"\/#",
"srccall":"OH7RDA",
"dstcall":"APND12",
"phg":"44603",
"comment":"\/R,W,Wn,Tn Siilinjarvi",
"path":"WIDE2-2,qAR,OH7AA"
}
]
}
Description of common fields:
Description of location record fields:
Additional fields for AIS targets:
Basic location query using XML:
https://api.aprs.fi/api/get?name=OH7RDA&what=loc&apikey=APIKEY&format=xml <?xml version="1.0" encoding="utf-8"?> <xml> <command>get</command> <result>ok</result> <what>loc</what> <found>1</found> <entries> <entry> <name>OH7RDA</name> <type>l</type> <time>1267445689</time> <lasttime>1270580127</lasttime> <lat>63.06717</lat> <lng>27.66050</lng> <symbol>/#</symbol> <srccall>OH7RDA</srccall> <dstcall>APND12</dstcall> <phg>44603</phg> <comment>/R,W,Wn,Tn Siilinjarvi</comment> <path>WIDE2-2,qAR,OH7AA</path> </entry> </entries> </xml>
Querying multiple targets using a single request:
You can request data for up to 20 targets by separating the callsigns using a comma. The rate limiting limits the amount of API queries over time, not the amount of targets queried. Batch queries of multiple stations are faster for you and generate less load on the server.
https://api.aprs.fi/api/get?name=OH7RDA,OH7AA&what=loc&apikey=APIKEY&format=json
{
"command":"get",
"result":"ok",
"what":"loc",
"found":2,
"entries": [
{
"name":"OH7RDA",
... other data ...
},
{
"name":"OH7AA"
... other data ...
}
]
}
Querying weather data:
Again, all data is returned in metric format: temperatures in degrees Celsius, wind speed in meters per second. Multiple stations may be requested by separating callsigns using the comma character, like in location queries described above.
https://api.aprs.fi/api/get?name=OH2TI&what=wx&apikey=APIKEY&format=json
{
"command":"get",
"result":"ok",
"what":"wx",
"found":1,
"entries": [
{
"name":"OH2TI",
"time":"1270580978",
"temp":"2.8",
"pressure":"1022.1"
"humidity":"88",
"wind_direction":"270",
"wind_speed":"2.7"
}
]
}
Fields:
Querying text messages:
This API call returns at most 10 latest APRS messages for the given recipient(s). Up to 10 recipients can be queried in a single call by separating the callsigns with a comma. The returned message ID can be used at your end to check whether new messages have been received since the last call.
https://api.aprs.fi/api/get?what=msg&dst=OH2TI&apikey=APIKEY&format=json
{
"command":"get",
"result":"ok",
"found":2,
"what":"msg",
"entries": [
{
"messageid":"1271366",
"time":"1272453795",
"srccall":"OH5KUY-4",
"dst":"OH2TI",
"message":"foo bar"
},
{
"messageid":"1271368",
"time":"1272454795",
"srccall":"OH5KUY-4",
"dst":"OH2TI",
"message":"bar foo"
}
]
}
Fields:
Error reporting:
When a request fails, result is set to fail and a human-readable error message is returned in description. Please make sure your application handles errors gracefully, reports them back to the user, and writes them to a log file so that you can inspect them later. aprs.fi uses UTC time in log files, and so should you.
https://api.aprs.fi/api/get?name=OH2TI&what=wx&apikey=WRONGAPIKEY&format=json
{
"command":"get",
"result":"fail",
"description":"authentication failed: wrong API key"
}
Happy hacking!