Callook.info API Reference

This document is an API reference for callook.info, geared towards software developers.

The callook.info API is publicly available and is free to use however you wish.

No advertisements of any kind appear on the site or in the data provided by its API.

If you have found the callook.info API useful for your application, please consider » donating « to help with hosting costs and to motivate future development and maintainence.

All donations are appreciated!

» Donate «


Contents


Callook.info Site and API History/Changelog


General API Information

Usage Terms

The callook.info API is publicly available and is free to use however you wish.

No advertisements of any kind appear on the site or in the data provided by its API.

Note that although callook.info strides to provide accurate callsign data and a stable API with minimal downtime, there are no guarantees regarding data accuracy or site uptime. If you find that callook.info is providing inaccurate data, please don't hesitate to contact its creator and maintainer, Josh Dick, W1JDD.

Callsign Data

Callook.info exclusively contains and serves United States callsign data. The site automatically updates its database daily at 11:00 AM ET, using publically available database snapshots provided by the FCC. The site temporarily goes offline while updating its database. During that time, the API will not serve callsign data (see below.) The daily update process usually takes less than five minutes.

There are currently no plans to expand callook.info to include callsign data from other countries, as its backend logic is very closely tied to the structure of the FCC's database snapshots. This allows the site to deliver callsign data as quickly and efficiently as possible.

Latitude, longitude and gridsquare information are not part of the FCC database, but are calculated on the fly by utilizing the Bing Maps API to translate the mailing address associated with a callsign to an approximate latitude and longitude, which are then converted to gridsquare format.

API Access

The callook.info API is accessed solely through simple HTTP GET requests. The API serves results with the appropriate HTTP header for the requested format.

Whenever data is requested for a callsign that is not active/currently held, but is an old callsign of a currently active licensee, the site and API will seamlessly serve the data for that licensee's current callsign.

Possible Values for Structured Fields (JSON/JSONP/XML)

There are two kinds of fields that appear in the JSON, JSONP or XML data returned from the callook.info API, "structured" fields and "unstructured" fields. A structured field's value is always drawn from a fixed set of values specific to that field (outlined below).

Any field that isn't specifically designated as a structured field below is considered to be an unstructured field. Values of unstructured fields are not drawn from a fixed set of values. An unstructured field may be set to the empty string if no data is available for that field for a given callsign.

Field Name Possible Values Notes
status VALID | INVALID | UPDATING If status isn't VALID, status is the only field that will appear in the output. However, whenever status is VALID, all other fields will always appear in the output. status will be VALID for valid callsigns, INVALID for invalid callsigns, and UPDATING if the site has temporarily gone offline to do its daily database update.
type CLUB | MILITARY | RACES | RECREATION | PERSON
operClass | class NOVICE | TECHNICIAN | TECHNICIAN PLUS | GENERAL | ADVANCED | EXTRA This field may be set to the empty string if no data is available for it for a given callsign (for example, for club callsigns.)


JSON/JSONP API

HTTP Header

When requesting data in JSON or JSONP format, callook.info serves the data with the following HTTP header:
Content-Type: application/json; charset=utf-8

URL Format

JSON data:
Format http://callook.info/[callsign]/json
Example http://callook.info/w1aw/json
Legacy Format http://callook.info/index.php?callsign=[callsign]&display=json
Legacy Example http://callook.info/index.php?callsign=w1aw&display=json
JSONP data:
Format http://callook.info/[callsign]/json/[callback_name]
Example http://callook.info/w1aw/json/test_callback
Legacy Format http://callook.info/index.php?callsign=[callsign]&display=json&callback=[callback]
Legacy Example http://callook.info/index.php?callsign=w1aw&display=json&callback=test_callback

Note that the API only allows alphanumeric characters, underscores (_), periods (.) and spaces ( ) to be specified for [callback]. All other characters will be stripped out of the output.

Return Value Information

This is an example of JSON-formatted data provided by the API:
{
  "status": "VALID",
  "type": "CLUB",
  "current": {
    "callsign": "W1AW",
    "operClass": ""
  },
  "previous": {
    "callsign": "",
    "operClass": ""
  },
  "trustee": {
    "callsign": "K1ZZ",
    "name": "SUMNER, DAVID G"
  },
  "name": "ARRL HQ OPERATORS CLUB",
  "address": {
    "line1": "225 MAIN ST",
    "line2": "NEWINGTON, CT 06111",
    "attn": "ATTN:  DAVID G SUMNER"
  },
  "location": {
    "latitude": "41.714776",
    "longitude": "-72.726744",
    "gridsquare": "FN31pr",
  },
  "otherInfo": {
    "grantDate": "12/02/2010",
    "expiryDate": "02/26/2021",
    "lastActionDate": "12/02/2010",
    "frn": "0004511143",
    "ulsUrl": "http://wireless2.fcc.gov/UlsApp/UlsSearch/license.jsp?licKey=780866"
  }
}
            
Data requested in JSON format will be structured like the example above. Data requested in JSONP format is structured in an identical matter, along with a user-specified JavaScript callback wrapped around the JSON data.


XML API

HTTP Header

When requesting data in XML format, callook.info serves the data with the following HTTP header:
Content-Type: text/xml; charset=utf-8

URL Format

XML data:
Format http://callook.info/[callsign]/xml
Example http://callook.info/w1aw/xml
Legacy Format http://callook.info/index.php?callsign=[callsign]&display=xml
Legacy Example http://callook.info/index.php?callsign=w1aw&display=xml

Return Value Information

This is an example of XML-formatted data provided by the API:
<callook>
  <status>VALID</status>
  <type>CLUB</type>
  <current>
    <callsign>W1AW</callsign>
    <class/>
  </current>
  <previous>
    <callsign/>
    <class/>
  </previous>
  <trustee>
    <callsign>K1ZZ</callsign>
    <name>SUMNER, DAVID G</name>
  </trustee>
  <name>ARRL HQ OPERATORS CLUB</name>
  <address>
    <line1>225 MAIN ST</line1>
    <line2>NEWINGTON, CT 06111</line2>
    <attn>ATTN:  DAVID G SUMNER</attn>
  </address>
  <location>
    <latitude>41.714776</latitude>
    <longitude>-72.726744</longitude>
    <gridsquare>FN31pr</gridsquare>
  </location>
  <otherinfo>
    <grantdate>12/02/2010</grantdate>
    <expirydate>02/26/2021</expirydate>
    <lastactiondate>12/02/2010</lastactiondate>
    <frn>0004511143</frn>
    <ulsurl>http://wireless2.fcc.gov/UlsApp/UlsSearch/license.jsp?licKey=780866</ulsurl>
  </otherinfo>
</callook>
           
Data requested in XML format will be structured like the example above.


Text API

HTTP Header

When requesting data in text format, callook.info serves the data with the following HTTP header:
Content-Type: text/plain; charset=utf-8

URL Format

Text data:
Format http://callook.info/[callsign]/textn
Example http://callook.info/w1aw/text
Legacy Format http://callook.info/index.php?callsign=[callsign]&display=text
Legacy Example http://callook.info/index.php?callsign=w1aw&display=text

Return Value Information

This is an example of text-formatted data provided by the API:
Type: CLUB
Callsign: W1AW
Trustee: SUMNER, DAVID G [K1ZZ]
Name + Address:
  ARRL HQ OPERATORS CLUB
  225 MAIN ST
  NEWINGTON, CT 06111
  ATTN:  DAVID G SUMNER
Location:
  Latitude: 41.714776
  Longitude: -72.726744
  Grid Square: FN31pr
  Quality: 87
Other License Information:
  Effective: 12/02/2010
  Expires: 02/26/2021
  Last Action: 12/02/2010
  FRN: 0004511143
           
Data requested in text format will be structured like the example above. If no data is available for an unstructured field for a given callsign, the field will be automatically omitted from the returned text.


List of Callook.info-Enabled Software

The following web sites and software use the callook.info API. If you're using the callook.info API for your software, contact Josh Dick, W1JDD to have it added to this list.

This document was last updated on March 29, 2014, and is valid HTML5. Please contact Josh Dick, W1JDD with any questions or comments about http://callook.info or its API.