goqrz

README

GoQRZ Library

GoQRZ is a simple Go Library which implements the QRZ.com specification.

Usage

First, import the library:

import "github.com/ocelotsloth/goqrz"

Next, create a new session, providing a QRZ.com username and password as well as a User Agent which identifies your program to the API service:

qrzSession := goqrz.GetSession("user", "pass", "userAgent")

Finally, request data using the GetCallsign or GetDXCC functions:

qrzSession.GetCallsign("KN4IJZ")

Documentation for the returned datatypes can be found via godoc or within the source code.

GoQRZ Command Line Interface

Included in this library is a CLI tool which can be used to query QRZ for information on callsigns and DXCC entities.

Install GoQRZ CLI

There are two ways to install and use the CLI; compiling from source and downloading precompiled binaries.

From Source

The CLI can be compiled from source by running the following:

go get github.com/ocelotsloth/goqrz/goqrz

Provided your GOPATH is configured correctly you should now be able to run goqrz from the command line.

Precompiled Binaries

Look at the releases on this GitHub page for downloadable binaries. This utility can be cross-compiled to most any popular archetecture in use. Open an issue if you need an additional archetecture added to the list of precompiled binaries.

CLI Usage

Before pulling data from the XML API, it is important to log in. Ensure 2 factor authentication is enabled on your account before using this utility! QRZ.com does not have encryption enabled on their XML endpoint, so it is imparative that this password be unique to QRZ.com. Be sure to change it frequently as well. This library does its best to remain secure by not storing your username or password between calls. Instead it provides two methods to store the session key.

Get Session Key

First, run goqrz login -u <username> -p <password> to receive your session key. The key is printed to stdout, so you can store it as an environment variable (store it to GOQRZ_KEY) or by passing the key to each subsequent call via the --key flag.

Query Data

There are two queries currently implemented: callsigns and dxcc zones.

Callsigns

To retrieve callsign data, use the command goqrz callsign [--key=<sessionKey>] Callsign [AdditionalCallsigns...]. To be efficient, please consider batching your callsign requests to one single call to the goqrz CLI. This will reduce the overhead with setting up the connection to QRZ.com.

Data is returned as JSON. I personally recommend using jq to further deal with the data.

DXCC Zones

DXCC data can be retrieved in the exact same fasion as Callsigns, except with the following syntax: goqrz dxcc [--key=<sessionKey>] DXCCID [AdditionalDXCCIDs...]

Documentation

Index

• func GetSessionKey(user string, pass string, agent string) (string, error)
• type Callsign
  • func GetCallsign(key string, callsign string, agent string) (Callsign, error)
• type DXCC
  • func GetDXCC(key string, dxcc string, agent string) (DXCC, error)
• type QRZDatabase
• type Session
  • func GetSession(key string, agent string) (Session, error)

Functions

func GetSessionKey

func GetSessionKey(user string, pass string, agent string) (string, error)

GetSessionKey takes user/pass and returns a valid session

Types

type Callsign

type Callsign struct {
	Callsign         string `xml:"call"`      // callsign
	CrossRef         string `xml:"xref"`      // Cross reference: the query callsign that returned this record
	Aliases          string `xml:"aliases"`   // Other callsigns that resolve to this record
	DXCCID           string `xml:"dxcc"`      // DXCC entity ID (country code) for the callsign
	FirstName        string `xml:"fname"`     // first name
	LastName         string `xml:"name"`      // last name
	Address1         string `xml:"addr1"`     // address line 1 (i.e. house # and street)
	Address2         string `xml:"addr2"`     // address line 2 (i.e, city name)
	State            string `xml:"state"`     // state (USA Only)
	Zip              string `xml:"zip"`       // Zip/postal code
	CountryName      string `xml:"country"`   // country name for the QSL mailing address
	DXCCEntityCode   string `xml:"ccode"`     // dxcc entity code for the mailing address country
	Lat              string `xml:"lat"`       // lattitude of address (signed decimal) S < 0 > N
	Lon              string `xml:"lon"`       // longitude of address (signed decimal) W < 0 > E
	GridLocator      string `xml:"grid"`      // grid locator
	County           string `xml:"county"`    // county name (USA)
	FIPSIdentifier   string `xml:"fips"`      // FIPS county identifier (USA)
	DXCCCountryName  string `xml:"land"`      // DXCC country name of the callsign
	EffectiveDate    string `xml:"efdate"`    // license effective date (USA)
	ExpirationDate   string `xml:"expdate"`   // license expiration date (USA)
	PreviousCall     string `xml:"p_call"`    // previous callsign
	Class            string `xml:"class"`     // license class
	Codes            string `xml:"codes"`     // license type codes (USA)
	QSLManager       string `xml:"qslmgr"`    // QSL manager info
	Email            string `xml:"email"`     // email address
	WebURL           string `xml:"url"`       // web page address
	QRZPageViews     string `xml:"u_views"`   // QRZ web page views
	BioByteLength    string `xml:"bio"`       // approximate length of the bio HTML in bytes
	LastBioUpdate    string `xml:"biodate"`   // date of the last bio update
	ImageURL         string `xml:"image"`     // full URL of the callsign's primary image
	ImageInfo        string `xml:"imageinfo"` // height:width:size in bytes, of the image file
	Serial           string `xml:"serial"`    // QRZ db serial number
	LastModDate      string `xml:"moddate"`   // QRZ callsign last modified date
	MetroServiceArea string `xml:"MSA"`       // Metro Service Area (USPS)
	TelAreaCode      string `xml:"AreaCode"`  // Telephone Area Code (USA)
	TimeZone         string `xml:"TimeZone"`  // Time Zone (USA)
	GMTOffset        string `xml:"GMTOffset"` // GMT Time Offset
	DSTObserved      string `xml:"DST"`       // Daylight Saving Time Observed
	EQSLAccepted     string `xml:"eqsl"`      // Will accept e-qsl (0/1 or blank if unknown)
	PaperQSLAccepted string `xml:"mqsl"`      // Will return paper QSL (0/1 or blank if unknown)
	CQZone           string `xml:"cqzone"`    // CQ Zone identifier
	ITUZone          string `xml:"ituzone"`   // ITU Zone identifier
	BirthDate        string `xml:"born"`      // operator's year of birth
	QRZCallManager   string `xml:"user"`      // User who manages this callsign on QRZ
	LOTWAccepted     string `xml:"lotw"`      // Will accept LOTW (0/1 or blank if unknown)
	IOTADesignator   string `xml:"iota"`      // IOTA Designator (blank if unknown)
	GeolocSource     string `xml:"geoloc"`    // Describes source of lat/long data
}

Callsign is documented in the standard.

func GetCallsign

func GetCallsign(key string, callsign string, agent string) (Callsign, error)

GetCallsign takes a callsign and returns the QRZ information on that callsign.

type DXCC

type DXCC struct {
	Dxcc      string `xml:"dxcc"`      // DXCC entity number for this record
	Cc        string `xml:"cc"`        // 2-letter country code (ISO-3166)
	Ccc       string `xml:"ccc"`       // 3-letter country code (ISO-3166)
	Name      string `xml:"name"`      // long name
	Continent string `xml:"continent"` // 2-letter continent designator
	Ituzone   string `xml:"ituzone"`   // ITU Zone
	Cqzone    string `xml:"cqzone"`    // CQ Zone
	Timezone  string `xml:"timezone"`  // UTC timezone offset +/-
	Lat       string `xml:"lat"`       // Latitude (approx.)
	Lon       string `xml:"lon"`       // Longitude (approx.)
	Notes     string `xml:"notes"`     // Special notes and/or exceptions
}

DXCC is defined by the following standard: https://www.qrz.com/XML/current_spec.html

func GetDXCC

func GetDXCC(key string, dxcc string, agent string) (DXCC, error)

GetDXCC takes a dxcc id and returns the QRZ information on that region.

type QRZDatabase

type QRZDatabase struct {
	Xmlns    string   `xml:"xmlns,attr"`   // XML Namespace
	Version  string   `xml:"version,attr"` // QRZ API Version
	Session  Session  `xml:"Session"`      // User Session data
	Callsign Callsign `xml:"Callsign"`     // Requested Callsign data
	DXCC     DXCC     `xml:"DXCC"`         // Requested DXCC Zone data
}

QRZDatabase is documented in the standard.

type Session

type Session struct {
	Key     string `xml:"Key"`     // a valid user session key
	Count   int    `xml:"Count"`   // Number of lookups performed by this user in the current 24 hour period
	SubExp  string `xml:"SubExp"`  // time and date that the users subscription will expire - or - "non-subscriber"
	GMTime  string `xml:"GMTime"`  // Time stamp for this message
	Message string `xml:"Message"` // An informational message for the user
	Error   string `xml:"Error"`   // XML system error message
	Remark  string `xml:"Remark"`  // Remarks are sometimes helpful diagnostic messages from QRZ.com
	// contains filtered or unexported fields
}

Session is documented in the standard.

func GetSession

func GetSession(key string, agent string) (Session, error)

GetSession creates a session object from just a key