Actions

Difference between revisions of "RadioReference.com Web Service3.1"

From The RadioReference Wiki

(Updated details for version 5 of SOAP2)
Line 97: Line 97:
 
== Versions ==
 
== Versions ==
  
The latest release of the Web service is '''5'''
+
The latest release of the Web service is '''6'''
 
+
* '''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 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.
  

Revision as of 12:25, 5 November 2009

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:

           http://www.radioreference.com/apps/account/?tab=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 release of the Web service is 6

  • 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/

Developer Tutorials and References