Class RadioReferenceService
java.lang.Object
io.github.dsheirer.rrapi.RadioReferenceService
Java client for accessing the radioreference.com web services API
Uses the Java HttpClient with no dependencies on legacy Axis 1.4 libraries.
Thread safe: methods can be called concurrently. Each request is limited by the connect and request timeouts, and
async(ServiceCall) runs any call in the background with cancellation.-
Nested Class Summary
Nested ClassesModifier and TypeClassDescriptionstatic interfaceA call of one or more service methods, for running withasync(ServiceCall) -
Field Summary
Fields -
Constructor Summary
ConstructorsConstructorDescriptionRadioReferenceService(AuthorizationInformation authorizationInformation) Constructs an instance of the serviceRadioReferenceService(AuthorizationInformation authorizationInformation, Duration connectTimeout, Duration requestTimeout) Constructs an instance of the service with custom timeouts -
Method Summary
Modifier and TypeMethodDescription<T> CompletableFuture<T> async(RadioReferenceService.ServiceCall<T> call) Runs the call on a new virtual thread and returns its result as a future, for example:voidClears the tags map so that it can be downloaded again on the next getTagsMap() invocationgetAgencyFrequenciesByTag(int agencyId, int tagId) Agency frequencies by taggetAgencyInfo(int agencyId) Agency information for a specific agencygetAgencyInfo(Agency agency) Agency information for a specific agencygetApco25Systems(String systemId) Query radio systems by APCO25 hexadecimal system identifier.getCounties(List<Integer> countyIds) Get a list of counties by county idList of countries supported by the web service.getCountry(int id) Retrieves the country by identifiergetCountryInfo(int countryId) Country information for a specific countrygetCountryInfo(Country country) Country information for a specific countrygetCountyFrequenciesByTag(int countyId, int tagId) County frequencies by taggetCountyInfo(int countyId) County information for a specific countygetFccCallsignDetails(String callsign) Get FCC callsign details.getFccCallsignsNearLocation(double latitude, double longitude, double range) Get FCC Callsigns near a locationgetFccRadioServiceCode(String code) Get FCC Radio Service Code Information for a specific codeGet FCC Radio Service Code InformationgetFlavor(int flavorId) Flavor informationMap of flavors and flavor identifiers.getMetro(int metroId) Metro informationgetMetroCounties(int metroId) Get counties for a metro areaMap of counties to metro identifiers.getMetrosByState(int stateId) List of metro areas for a state WARNING: the first call to this method is expensive because it uses getMetroCountiesMap() which is expensive.Map of metros and metro identifiers.getMode(int modeId) Mode informationMap of modes and mode identifiers.getSites(int systemId) Get sites for a radio systemgetState(int stateId) Get stategetStateInfo(int stateId) Get state infoGet a list of states by state idgetSubCategoryFrequencies(int subCategoryId) Sub-Category frequenciesgetSystemInformation(int systemId) Radio system information and detailsgetTag(int tagId) TagMap of tags and tag identifiers Note: map is cached on first call to the web service and reused on subsequent method invocations.getTalkgroupCategories(int systemId) Get talkgroup categoriesgetTalkgroups(int systemId) Get talkgroups for a specific systemgetTalkgroups(TalkgroupRequestFilter filter) Get talkgroups for a specific system with optional filtering by category, tag, or decimal valuegetType(int typeId) Type (protocol) informationMap of types (protocols) and type identifiers Note: type map is cached on first call to the web service and reused on subsequent method invocations.List of icecast audio streaming feed configurations that the user is authorized to provide to broadcastify.comUser information containing user name and account expiration dategetVoice(int voiceId) Voice informationMap of voices and voice identifiers Note: map is cached on first call to the web service and reused on subsequent method invocations.getZipcodeInfo(int zipcode) Zipcode informationsearchCountyFrequencies(int countyId, double frequency) Search county frequenciessearchCountyFrequencies(int countyId, double frequency, String tone) Search county frequenciessearchMetroFrequencies(int metroId, double frequency) Search metro frequenciessearchMetroFrequencies(int metroId, double frequency, String tone) Search metro frequenciessearchStateFrequencies(int stateId, double frequency) Search state frequenciessearchStateFrequencies(int stateId, double frequency, String tone) Search state frequencies
-
Field Details
-
API_VERSION
Radio Reference API version supported by this service.- See Also:
-
DEFAULT_CONNECT_TIMEOUT
Default limit for establishing a connection to the web service -
DEFAULT_REQUEST_TIMEOUT
Default limit for receiving the response to a request, after the request is sent
-
-
Constructor Details
-
RadioReferenceService
public RadioReferenceService(AuthorizationInformation authorizationInformation) throws RadioReferenceException Constructs an instance of the service- Parameters:
authorizationInformation- with username and password for accessing the web service- Throws:
RadioReferenceException- if there are any errors while accessing the service
-
RadioReferenceService
public RadioReferenceService(AuthorizationInformation authorizationInformation, Duration connectTimeout, Duration requestTimeout) throws RadioReferenceException Constructs an instance of the service with custom timeouts- Parameters:
authorizationInformation- with username and password for accessing the web serviceconnectTimeout- limit for establishing a connection to the web servicerequestTimeout- limit for receiving the response to each request- Throws:
RadioReferenceException- if the authorization information is nullIllegalArgumentException- if a timeout is null, zero or negative
-
-
Method Details
-
getUserInfo
User information containing user name and account expiration date- Returns:
- user information instance or null
- Throws:
RadioReferenceException- if there is an error
-
getUserFeeds
List of icecast audio streaming feed configurations that the user is authorized to provide to broadcastify.com- Returns:
- list of broadcastify.com feed configurations or an empty list
- Throws:
RadioReferenceException- if there is an error
-
getCountry
Retrieves the country by identifier- Parameters:
id- of the country- Returns:
- country if found, otherwise throws exception
- Throws:
RadioReferenceException- if there is an error
-
getCountries
List of countries supported by the web service.- Returns:
- list of countries or empty list
- Throws:
RadioReferenceException- if there is an error
-
getCountryInfo
Country information for a specific country- Parameters:
country- to query- Returns:
- country information or null
- Throws:
RadioReferenceException- if there is an error
-
getCountryInfo
Country information for a specific country- Parameters:
countryId- to query- Returns:
- country information or null
- Throws:
RadioReferenceException- if there is an error
-
getAgencyInfo
Agency information for a specific agency- Parameters:
agency- to query- Returns:
- agency information or null
- Throws:
RadioReferenceException- if there is an error
-
getAgencyInfo
Agency information for a specific agency- Parameters:
agencyId- to query- Returns:
- agency information or null
- Throws:
RadioReferenceException- if there is an error
-
getState
Get state- Parameters:
stateId- to query- Returns:
- state or null
- Throws:
RadioReferenceException- if there is an error
-
getStateInfo
Get state info- Parameters:
stateId- to query- Returns:
- state info or null
- Throws:
RadioReferenceException- if there is an error
-
getStates
Get a list of states by state id- Parameters:
stateIds- to query- Returns:
- list of states or empty list
- Throws:
RadioReferenceException- if there is an error
-
getCounties
Get a list of counties by county id- Parameters:
countyIds- to query- Returns:
- list of counties or empty list
- Throws:
RadioReferenceException- if there is an error
-
getCountyInfo
County information for a specific county- Parameters:
countyId- to query- Returns:
- county information or null
- Throws:
RadioReferenceException- if there is an error
-
getCountyFrequenciesByTag
public List<Frequency> getCountyFrequenciesByTag(int countyId, int tagId) throws RadioReferenceException County frequencies by tag- Parameters:
countyId- to querytagId- to query- Returns:
- frequencies list
- Throws:
RadioReferenceException- if there is an error
-
getAgencyFrequenciesByTag
public List<Frequency> getAgencyFrequenciesByTag(int agencyId, int tagId) throws RadioReferenceException Agency frequencies by tag- Parameters:
agencyId- to querytagId- to query- Returns:
- frequencies list
- Throws:
RadioReferenceException- if there is an error
-
getSystemInformation
Radio system information and details- Parameters:
systemId- to query- Returns:
- radio system or null
- Throws:
RadioReferenceException- if there is an error
-
getApco25Systems
Query radio systems by APCO25 hexadecimal system identifier.- Parameters:
systemId- to query (e.g. '2AE')- Returns:
- list of radio systems or null
- Throws:
RadioReferenceException- if there is an error
-
getSites
Get sites for a radio system- Parameters:
systemId- to query- Returns:
- list of sites or null
- Throws:
RadioReferenceException- if there is an error
-
getTalkgroups
Get talkgroups for a specific system- Parameters:
systemId- to query- Returns:
- list of talkgroups or null
- Throws:
RadioReferenceException- if there is an error
-
getTalkgroups
Get talkgroups for a specific system with optional filtering by category, tag, or decimal value- Parameters:
filter- specifying a category id, tag id, or decimal value- Returns:
- list of talkgroups or null
- Throws:
RadioReferenceException- if there is an error
-
getTalkgroupCategories
Get talkgroup categories- Parameters:
systemId- to query- Returns:
- list of talkgroup categories or null
- Throws:
RadioReferenceException- if there is an error
-
getFlavor
Flavor information- Parameters:
flavorId- to query- Returns:
- flavor or null
- Throws:
RadioReferenceException- if there is an error
-
getFlavorsMap
Map of flavors and flavor identifiers. Note: flavor values are cached on the first web service call and reused for subsequent method invocations.- Returns:
- read-only flavors map or null
- Throws:
RadioReferenceException- if there is an error
-
getMode
Mode information- Parameters:
modeId- to query- Returns:
- mode or null
- Throws:
RadioReferenceException- if there is an error
-
getModesMap
Map of modes and mode identifiers. Note: mode values are cached on the first web service call and reused for subsequent method invocations.- Returns:
- read-only modes map or null
- Throws:
RadioReferenceException- if there is an error
-
getMetro
Metro information- Parameters:
metroId- to query- Returns:
- metro or null
- Throws:
RadioReferenceException- if there is an error
-
getMetrosMap
Map of metros and metro identifiers. Note: metro values are cached on the first web service call and reused for subsequent method invocations.- Returns:
- read-only metros map or null
- Throws:
RadioReferenceException- if there is an error
-
getMetroCountiesMap
Map of counties to metro identifiers. Note: this is an expensive service call the first time. Metro values are cached on the first web service call and reused for subsequent method invocations.- Returns:
- read-only metro counties map or null
- Throws:
RadioReferenceException- if there is an error
-
getMetroCounties
Get counties for a metro area- Parameters:
metroId- to query- Returns:
- list of counties
- Throws:
RadioReferenceException- if there is an error
-
getMetrosByState
List of metro areas for a state WARNING: the first call to this method is expensive because it uses getMetroCountiesMap() which is expensive. Note: this is performed by first querying the state info for the list of counties and finding the matching metro areas from the getMetrosMap() method.- Parameters:
stateId- to query- Returns:
- list of metros
- Throws:
RadioReferenceException- if there is an error with the web service
-
getTagsMap
Map of tags and tag identifiers Note: map is cached on first call to the web service and reused on subsequent method invocations.- Returns:
- read-only tags map or null
- Throws:
RadioReferenceException- if there is an error
-
clearTagMap
public void clearTagMap()Clears the tags map so that it can be downloaded again on the next getTagsMap() invocation -
getTag
Tag- Parameters:
tagId- to query- Returns:
- type or null
- Throws:
RadioReferenceException- if there is an error
-
getType
Type (protocol) information- Parameters:
typeId- to query- Returns:
- type or null
- Throws:
RadioReferenceException- if there is an error
-
getTypesMap
Map of types (protocols) and type identifiers Note: type map is cached on first call to the web service and reused on subsequent method invocations.- Returns:
- read-only types map or null
- Throws:
RadioReferenceException- if there is an error
-
getVoicesMap
Map of voices and voice identifiers Note: map is cached on first call to the web service and reused on subsequent method invocations.- Returns:
- read-only voices map or null
- Throws:
RadioReferenceException- if there is an error
-
getVoice
Voice information- Parameters:
voiceId- to query- Returns:
- voice or null
- Throws:
RadioReferenceException- if there is an error
-
getZipcodeInfo
Zipcode information- Parameters:
zipcode- to query- Returns:
- zipcode info or null
- Throws:
RadioReferenceException- if there is an error
-
getSubCategoryFrequencies
Sub-Category frequencies- Parameters:
subCategoryId- that identifies a set of frequencies- Returns:
- list of frequencies
- Throws:
RadioReferenceException- if there is an error
-
searchCountyFrequencies
public List<SearchFrequencyResult> searchCountyFrequencies(int countyId, double frequency) throws RadioReferenceException Search county frequencies- Parameters:
countyId- that identifies a set of frequenciesfrequency- in MHz- Returns:
- list of search results
- Throws:
RadioReferenceException- if there is an error
-
searchCountyFrequencies
public List<SearchFrequencyResult> searchCountyFrequencies(int countyId, double frequency, String tone) throws RadioReferenceException Search county frequencies- Parameters:
countyId- that identifies a set of frequenciesfrequency- in MHztone- description (optional - can be null)- Returns:
- list of search results
- Throws:
RadioReferenceException- if there is an error
-
searchStateFrequencies
public List<SearchFrequencyResult> searchStateFrequencies(int stateId, double frequency) throws RadioReferenceException Search state frequencies- Parameters:
stateId- that identifies a set of frequenciesfrequency- in MHz- Returns:
- list of search results
- Throws:
RadioReferenceException- if there is an error
-
searchStateFrequencies
public List<SearchFrequencyResult> searchStateFrequencies(int stateId, double frequency, String tone) throws RadioReferenceException Search state frequencies- Parameters:
stateId- that identifies a set of frequenciesfrequency- in MHztone- description (optional - can be null)- Returns:
- list of search results
- Throws:
RadioReferenceException- if there is an error
-
searchMetroFrequencies
public List<SearchFrequencyResult> searchMetroFrequencies(int metroId, double frequency) throws RadioReferenceException Search metro frequencies- Parameters:
metroId- that identifies a set of frequenciesfrequency- in MHz- Returns:
- list of search results
- Throws:
RadioReferenceException- if there is an error
-
searchMetroFrequencies
public List<SearchFrequencyResult> searchMetroFrequencies(int metroId, double frequency, String tone) throws RadioReferenceException Search metro frequencies- Parameters:
metroId- that identifies a set of frequenciesfrequency- in MHztone- description (optional - can be null)- Returns:
- list of search results
- Throws:
RadioReferenceException- if there is an error
-
getFccCallsignDetails
Get FCC callsign details.- Parameters:
callsign- to query- Returns:
- callsign details or null
- Throws:
RadioReferenceException- if there is an error
-
getFccRadioServiceCodes
Get FCC Radio Service Code Information- Returns:
- list of FCC radio service codes
- Throws:
RadioReferenceException- if there is an error
-
getFccRadioServiceCode
Get FCC Radio Service Code Information for a specific code- Parameters:
code- to lookup that is composed of two letters- Returns:
- FCC radio service code or null
- Throws:
RadioReferenceException- if there is an error
-
getFccCallsignsNearLocation
public List<ProximityCallsignResult> getFccCallsignsNearLocation(double latitude, double longitude, double range) throws RadioReferenceException Get FCC Callsigns near a location- Parameters:
latitude- of the search locationlongitude- of the search locationrange- from the search location (0 - 4.82 km)- Returns:
- list of search results
- Throws:
RadioReferenceException- if there is an error
-
async
Runs the call on a new virtual thread and returns its result as a future, for example:
Cancelling the returned future interrupts the call, which aborts the HTTP request in progress. Cancel the returned future itself: cancelling a future derived from it, e.g. with thenApply(), doesn't interrupt the call.CompletableFuture<List<SearchFrequencyResult>> results = service.async(s -> s.searchCountyFrequencies(countyId, 460.0375));- Type Parameters:
T- result type- Parameters:
call- of one or more service methods- Returns:
- future that completes with the result, or exceptionally with a RadioReferenceException
-