RadioReference.com Web Service3.1

Overview

RadioReference.com is pleased to announce the SOAP2 release of the RadioReference.com Web service to the development community. SOAP2 is based on the Simple Object Access Protocol (SOAP), which is a standard for exchanging XML-based messages over computer networks.

The SOAP2 release is an important one for developers of applications that use RadioReference data, since it provides developers with a much easier to use abstract interface to the data, and it also provides a number of new features and data access methods for RadioReference.com data.

Some new features and methods include:

Ability to request specific versions and SOAP styles
Access to FCC License Data and FCC License proximity searches
Function tag data available for frequencies and talkgroups
Location based information
Searches across states, counties, and metro areas for radio data
User profile and subscription information
United States Zip code information
Better error handling

RRWsdl

The Web service WSDL can be found at the following URL:

http://api.radioreference.com/soap2/?wsdl&v=[version]&s=[style]

Where:

v = requested SOAP2 version [optional],  Possible values are a integer for
    the version number or "latest" for the latest version.
    If not specified, then the base version "1" is assumed.
s = SOAP response style [optional].  Possible values are "rpc" which is
    rcp/encoded, and "doc" which is document/literal.  If not 
    specified, "rpc" is assumed.

Without the optional parameters the WSDL request is:

http://api.radioreference.com/soap2/?wsdl

Common Input Parameters

All input parameters are clearly documented in the WSDL, however the following notes are important.

Most methods on the SOAP interface require authentication information, which should be submitted in an array called "authInfo" with the following members:

$authInfo = ("appKey" => "yourAssignedAppKey",
             "username" => "RRMemberUserName",
             "password" => "RRMemberPassword",
             "version" => "ServiceVersion",
             "style" => "SOAPReturnStyle",)

Parameters:

appKey   = Your assigned application key [required].  Developers should apply for a
           separate application key for each application they designed to use the Web
           service.  This parameter is required.
         
           Application Keys can be requested at:

           https://www.radioreference.com/account/api

username = The member's RadioReference.com Username [required]

password = The member's RadioReference.com Password [required]

version  = Web service Version [optional]. 

           Possible Values are an integer for the version number or "latest"
           for the latest version. If not specified, then the base version "1" is
           assumed. See the version section on this page for information on each
           version release.

style    = SOAP messaging style [optional].  
           Possible values are "rpc" which is rcp/encoded, and "doc" which is 
           document/literal.  If not specified, "rpc" is assumed.

NOTE: You should never, ever hard-code a username and password into an application. A user of your application should always be prompted for their RadioReference.com username and password. For access to the Web service, that member's account must be in good standing and paid in full as a Premium Subscriber on RadioReference.com.

Suggested Uses of New Features

These following methods and features are new to the Web service. A short description and potential application of the new methods are listed below.

Method: getZipCodeInfo

getZipCodeInfo returns the countyId, stateId, city name, latitude and longitude for a United States zip code. A software developer could prompt a user for a zip code and then execute programming actions or data reporting based upon a user's zip code.

Method: getUserData

getUserData returns the current authenticated user's premium subscription status. This would allow a software developer to report to the user the status of their subscription and when it is set to expire.

Methods: getCountyFreqsByTag / getAgencyFreqsByTag

getCountyFreqsByTag returns an array of frequency data based on a specified county and Tag. A software developer could program "All Fire Dispatch Frequencies in El Paso County, Colorado" with this specified Web service query.

Methods: searchCountyFreq / searchMetroFreq / searchStateFreq

These methods return an array of frequency data based on the requested location entity and frequency. Within a software application, an user could potentially specify their "home" county, state, or metro area, and have frequency results instantly shown to them when searching specific ranges for activity.

Versions

The latest production release of the Web service is 18 - "latest"

Version 18:

Added the TDMA Control Channel attribute (tdma_cc) to the TrsSite definition

Version 17:

Split out NXDN Mode types between NXDN48 and NXDN96

Version 16:

Added rectangle location data support for the following entities
- Counties
- Agencies
- Frequency Subcategories
- Trunked Systems
- Trunked Sites
- Trunked Talkgroup Categories

Cleaned up location data returns to prevent repeating inherited location data for all entities

Added Model System ID attribute for NXDN and DMR Tier III systems

Version 15:

Added "enc" attribute to frequencies and trunked system talkgroups.  
The "enc" attribute represents the use of encryption on the frequency or talkgroup.  

Possible values are:
0 = no encryption
1 = mixed encryption
2 = fully encrypted

Version 14:

Trunked Site

Added RAN attribute for NXDN trunked system sites

Version 13:

Conventional Frequencies

Added DMR Color Code attribute (colorCode)
Added DMR Talkgroup attribute (tg)
Added DMR Slot attribute (slot)

Trunked Site Frequencies

Added DMR Color Code attribute (colorCode)
Added NXDN Channel ID attribute (ch_id)

Trunked Talkgroups

Added slot attribute for DMR Conventional Networked system talk groups (slot)

Version 12:
- Web service no longer returns deprecated trunked radio systems when queried by system ID.

Version 11:
- Web service now returns trunked system site geolocation information in the following inheritance order:

For trunked systems that reside in a single county:

Use assigned site geolocation data
Use system default geolocation data
Use the site's county default geolocation data

For trunked systems that reside in multiple counties:

Use assigned site geolocation data
Use the site's county default geolocation data
Use system default geolocation data

Version 10:
- Changed the type for the towerId attribute from int to string in the WSDL
Version 9:
- The getCountryInfo method now returns the country name, country ID, country code, a list of states, and a list of nationwide agencies. Nationwide agencies are going to be a new part of the RadioRefernece.com database and will be used to represent common frequencies that are used within an entire country. The getCountryInfo method previously only returned a list of states.
- The getTrsSites method now returns the following additional attributes for each site: RFSS and NAC. These are attributes related to Project 25 trunking sites that we will now be tracking in the database.
- The subcategory object definition has been updated to include a list of trunked radio system SIDs that are associated with a subcategory. The subcategory object is returned from getAgencyInfo and getCountyInfo methods. there are instances in the RadioReference.com database where we add an associated trunked radio system to a conventional frequency subcategory, so this now allows you to consume those relationships and present them in your applications.
- Frequency Search methods have significantly increased performance.
Version 8:
- Minor changes to propagate inherited location based data for trunked systems, trunked sites, and trunked talkgroup categories.
Version 7:
- getTrsDetails now returns only custom frequency tables not assigned to any individual sites
- rebounded flag data type was decimal in WSDL, changed to int
- splinter flag data type was decimal in WSDL, changed to int
- getTrsSites now properly reports site SID in all instances
- NOAA SAME FIPS Code added to result (CountyInfo) from getCountyInfo method for US Counties
Version 6 - Added TrsBandPlan definition to TrsSite for multiple custom frequency tables and bandplans assigned to Motorola System sites. Fixed typo in TrsBrandPlan to TrsBandPlan. Power attribute for fccFrequency definition type changed from int to decimal.
Version 5 - Issued a fix for the getUserData method which returned a subscription expiration date in 1969 for admins and feed providers. Now returns "Never - Feed Provider" and "Never - Admin" in string format. Also fixed a WSDL schema error for fccLocation, where int return types for antennaHeight, structureHeight, and elevation should have been in decimal format.

Version 4 - Added method getUserFeedBroadcasts which returns audio feed broadcast information for the authenticated user. Input is the authInfo array. Return is userFeedBroadcasts which is an array of userFeedBroadcast entities:

userFeedBroadcast(
     feedId,
     descr,
     hostname,
     port,
     mount,
     password
)

Version 3 - Added attributes "rebanded" and "splinter" to the Sites definition. getTrsSites will now return these two attributes for each site, which indicates whether or not the site is rebanded to the new 800 MHz US Bandplan, or if the site uses the splinter type bandplan common for systems near the US/Mexican border. "1" == yes, "0" == no.
Version 2 - Fixed typo in WSDL for getTrsSites request: updated "siteFeqs" to "siteFreqs". Added trunked system zone support to getTrsSites request by adding attributes "zoneNumber" and "zoneDescr" to the request return. Those values will be set to NULL in cases where zones are not enabled for a trunked system.

Version 1 - Base Release

Support Mailing List

There is a dedicated YahooGroups mailing list for announcements and support related to the Web service. All developers of applications that use the Web service are highly encourage to subscribe to this list:

http://tech.groups.yahoo.com/group/rr_web_service/