AstroApp APIs: The Reference Guide


Access


The following call must be present in the HTML header:
<script type="text/javascript" src="http://astroapp.com/astro/astroapi?key=YOUR_ASTROAPP_API_KEY"></script>

Make sure to provide your generated AstroApp API Access Key in place of the YOUR_ASTROAPP_API_KEY string.

API Placement

The following line defines where a chart image is going to be shown on your page:
<div id="astroappDiv"></div>


API Reference

The main class that must be instantiated is AstroApp.
You can create an instance of this class by using a regular javascript notation: var astroapp = new AstroApp();
After defining the instance of the class, you can reference it by using the astroapp variable.


Submitting requests

    astroRun(astroApp, [callback]) - this is the main function that requests data and parses the response.
    Parameters:
        astroApp - type: AstroApp object. Please see details about the AstroApp class below.
        callback  - type: function. This parameter is optional and is only required if detailed information about planets, house cusps, or aspects was requested.
    Example:
        astroRun(astroapp, function(results){
            var lng, aspName;
            var pathLng          = "/calres/bodies/p/lng";
            var pathAspName = "/aspects/p/aspect/aspName";

            //Longitude of the Sun               
            var nodes=results.objectsXML.evaluate(pathLng, results.objectsXML, null, XPathResult.ANY_TYPE, null);
            var rslt=nodes.iterateNext();
            lng = rslt.childNodes[AstroApp.PLANET_SUN].nodeValue;
               
            //First aspect of the Sun
            nodes=results.aspectsXML.evaluate(pathAspName, results.aspectsXML, null, XPathResult.ANY_TYPE, null);
            var rsltAsp=nodes.iterateNext();
            aspName = rsltAsp.childNodes[AstroApp.PLANET_SUN].nodeValue;
        });


AstroApp Class


Constructors:
    AstroApp()   - creates a new instance of the AstroApp class.
    Parameters: this constructor does not accept any parameters.


Instance methods:
    setLongitude(longitude) - sets geographical longitude.
    Parameters: longitude - String in 37N|S55 format. The first 2 digits are degrees, the letter in the middle defines South (S) or North (N) longitude, and the last 2 digits are minutes of the longitude.
    Returns: The method does not return any value.
    Example: setLatitude("37N55");

    setLatitude(latitude) - sets geographical latitude.
    Parameters: latitude - String in 122E|W25 format. The first 3 digits are degrees, the letter in the middle defines East (E) or West (W) latitude, and the last 2 digits are minutes of the latitude.
    Returns: The method does not return any value.
    Example: setLatitude("122W25");

    setHeight(height) - sets the elevation of the geographical place in meters. This method is optional, if omitted, the default elevation value will be set to 0 meters.
    Parameters: height - number within -900 to 10,000 meters range.
    Returns: The method does not return any value.
    Example: setHeight(100); //This call will set the height to be 100 meters above the sea level.

    setDate(date) - sets the date.
    Parameters: date - String in YYYY:MM:DD format (4 digits for a year, 2 digits for a month and 2 digits for a day, all separated by the colon (":") or slash ("/") character.
    Returns: The method does not return any value.
    Example: setDate("2012:01:25"); //This call will set the date to January 25th, 2012.

    setTime(time) - sets the time.
    Parameters: time - String in HH:MM:SS format (2 digits for an hour in 24 hours format, 2 digits for minutes and 2 digits for seconds, all separated by the colon (":") character.
    Returns: The method does not return any value.
    Example: setTime("01:30:00"); //This call will set the time to 01 hour 30 minutes 0 seconds (01:30 AM).

    setTimeZone(timeZone) - sets the time zone offset.
    Parameters: time - String in [+-]HH:MM format (+ or - define whether to add or subtract the timezone offset, 2 digits for an hour in 24 hours format, 2 digits for minutes, with hour and minutes values separated by the colon (":") character.
                        this function cal also accept timeZoneID values returned by the needTZ(countryID, cityName) function.
    Returns: The method does not return any value.
    Example: setTimeZone("-08:00"); //This call will set the time zone to -8 hours.

    setAyanamsa(ayanamsa) - defines weather tropical zodiac or sidereal (ayanamsa value) to be used.
    Parameters: ayanamsa - one of the static values defined in the AstroApp class. See Static Values section for details.
                       The call to this method is optional. By default, the Tropical Zodiac will be used (AstroApp.NO_AYANAMSA).
    Returns: The method does not return any value.
    Example: setAyanamsa(AstroApp.AYANAMSA_LAHIRI); //This call will ensure that calculations are done using Lahiri ayanamsa.
                   setAyanamsa(AstroApp.NO_AYANAMSA); //This call will ensure the Tropical Zodiac is used.
                    If the setAyanamsa() method is never called, the results will be identical to the setAyanamsa(AstroApp.NO_AYANAMSA) call.

    setHouseSys(house_system) - defines the house system to be used.
    Parameters: house_system - one of the static values defined in the AstroApp class. See Static Values section for details.
                       The call to this method is optional. By default, the Placidus house system will be used (AstroApp.HOUSE_PLACIDUS).
    Returns: The method does not return any value.
    Example: setHouseSys(AstroApp.HOUSE_WHOLE_SIGN); //This call will ensure that calculations will be done using the Whole House system.
                   setHouseSys(AstroApp.HOUSE_PLACIDUS); //This call will ensure the Placidus House system is used.
                    If the setHouseSys() method is never called, the results will be identical to the setHouseSys(AstroApp.HOUSE_PLACIDUS) call.

    setCoordSys(coordinates_system) - defines the coordinates system to be used. Geocentric is the default value.
    Parameters: coordinates_system - one of the static values defined in the AstroApp class. See Static Values section for details.
                       The call to this method is optional. By default, the Geocentric coordinates system will be used (AstroApp.COORD_GEO).
    Returns: The method does not return any value.
    Example: setCoordSys(AstroApp.COORD_HELIO); //This call will ensure that calculations will be done using the Heliocentric coordinates system.
                   setCoordSys(AstroApp.COORD_GEO); //This call will ensure the Geocentric coordinates are used.
                    If the setCoordSys() method is never called, the results will be identical to the setCoordSys(AstroApp.COORD_GEO) call.

    setVarga(vargaNum) - sets the varga for Vedic Astrology calculations.
    Parameters: coordinates vargaNum - this is the varga number.
    Returns: The function does not return any value.
    Example: setVarga(9); //This will ensure calculates are done using D9 (Navamsa) varga.

    setLanguage() - call this function if you want to localize the output of AstroApp APIs.
    Parameters: (AstroApp.LANG_ENGLISH | AstroApp.LANG_GERMAN | AstroApp.LANG_JAPANESE)
    Returns: The method does not return any value.
    Example: setLanguage(AstroApp.LANG_ENGLISH); //This ensures that the output will be returned in English.

    setStyle() - call this function to customize the appearance of charts.
    Parameters: AstroApp.STYLE_* constants. Please see below the list of static values that can be used.
    Returns: The method does not return any value.
    Example: setStyle(AstroApp.STYLE_INDIAN_SOUTH); //This ensures that the chart will be drawn in the South Indian style format.

    needImage() - call this function if you need to get an image of the chart.
    Parameters: this function does not accept any parameters.
    Returns: The method draws the chart into the astroappDiv area. Please note that <div id="astroappDiv"></div> must be defined in your HTML page.

    needObjects() - call this function if you need to get XML data for planets and for house cusps. Planets information includes longitude, latitude, and speed. Houses information includes positions of all house cusps.
    Parameters: this function does not accept any parameters.
    Returns: The method returns XML string and also corresponding XML Document with detailed information about the planets and house cusps. The output can be obtained via the astroRun callback function.

    needAspects() - call this function if you need to get XML for aspects data. Aspects information includes IDs of planets in aspects, aspect value, aspect name, and applying vs separating indicator.
    Parameters: this function does not accept any parameters.
    Returns: The method returns XML string and also corresponding XML Document with detailed information about the aspects. The output can be obtained via the astroRun callback function.

    needTZ(countryID, cityName) - call this function if you need to get and use time zone information for the provided location
    Parameters: countryID - id of the country. Please contact AstroApp Support if you need the complete list of countryIDs that can be used with AstroApp APIs.
                       cityName - name of the city or location
    Returns: The function returns time zone ID, which can then be used in your setTimeZone(timeZoneID) function calls.
    Example: needTZ(1, "New York"); //this call will return time zone id for New York in the USA. Sample country IDs: 1: USA, 31: Brazil, 47: China, 80: France; 88: Germany; 114: Italy; 236: Great Britain.
   

    calcMidpoint(lng1, lng2) - call this function if you need to get the longitude of the midpoint between two objects. The function is designed to be called on the client side and does not require a server request.
    Parameters:   lng1 - longitude of the first object
                         lng2 - longitude of the second object
    Returns:  longitude of the midpoint between the provided objects.

     calcIsInAspect(lng1, lng2, aspAngle, orb) - call this function to test if the two specified objects are in the aspect. The function is designed to be called on the client side and does not require a server request.
    Parameters:   lng1 - longitude of the first object
                         lng2 - longitude of the second object
                         aspAngle - angle of the aspect. For example, to check if objects are in sextile, set aspAngle to 60.0.
                         orb - orb of the aspect.
    Returns:  true if objects are in aspect within the provided orb, false - if the objects are not in aspect.
    Example: calcIsInAspect(lngSun, lngMoon, 60.0, 5.0); //checks if the Sun and the Moon are in sextile aspect with 5 degree orb, where lngSun and lngMoon are ecliptic longitudes of the Sun and the Moon respectively.

    degnorm(lng) - this function normalizes the provided longitude to 360 degree value. The function is designed to be called on the client side and does not require a server request.
    Parameters:   lng - longitude value to be normalized to 360 degrees.
    Returns:  the normalized longitude value.

    difdeg2n(lng1, lng2) - this function calculates the difference between two longitudes and normalizes the result to a range of -180.0 <= x < 180.0 degrees.
    Parameters:  lng1 - longitude of the first object
                        lng2 - longitude of the second object
    Returns:  normalized angle between the two objects

    getSignNumber(lng) - this function returns the sign number of the provided longitude.
    Parameters:    lng - longitude of the point
  Returns:          sign number (1 is Aries, 2 is Taurus and so on).
  Example:         getSignNumber(181.50); //this call will return 7 (which is the sign of Libra).

    getLngInSign(lng) - this function returns relative position of the object in its Zodiac Sign
      Parameters:    lng - longitude of the point
    Returns:          longitude within the sign.
    Example:         getLngInSign(181.50); //this call will return 1.50.


  getHouseNumber(lng, housesArr) - this function returns the house number the provided point is in.
  Parameters:    lng - longitude of the point
                        houseArr - array of house cusps, where id is the house number and the value is the longitude of the house cusp. For example: [1:30.0; 2:60:0...] - first house cusp is at 30.0 degrees, 2nd house cups is at 60 degrees. You can get the house cusps data by calling the needObjects() function.
  Returns:          the house number the point is in.
Example:         getHouseNumber(33.0, houseArr); //using sample house cusps above this call will return 1, as the provided longitude is in the first house.

roundNum(number, decimalPlace) - this function will round the number to the decimal place provided
Parameters:    number - number to round
                      decimalPlace - decimal place to round the number to
Returns:          the number rounded to the decimalPlace specified
Example:         roundNum(181.5498, 2); //this call will return 181.55.

decimalMin2Minute(time) - this function will convert decimal representation of minutes into minutes.
Parameters:    time - the decimal representation of the time value.
Returns:          minutes value

degrees2DegMinSign(lng) - this function returns sign number, degree and minute values for the provided longitude
Parameters:    lng - longitude of the point
Returns:         a structure that contains sign number, degree and minute values for the provided longitude:
                    {
                      sign: signNum,
                      deg:  degree,
                      min:  minute
                    }
Example:         degrees2DegMinSign(181.50); //this call will return the following object {sign:7, deg:181, min:30};


    inRange(lng, range) - this function ensures the provided longitude is recalculated within the range. It can be useful for calculating planetary positions in Uranian Dials and in certain Vedic calculations.
    Parameters:   lng - longitude value.
                         range - range for conversion. In case of Uranian dials, this is the dial factor (for example: 45 degrees, 90 degrees, and so on).
    Returns:  the normalized longitude value.
    Example: inRange(lngSun, 90.0); //computes position of the Sun on the 90 degree dial.

    isInRange(lng, start, end) - this function checks if the provided longitude is within the range of longitudes outlined by the star and the end values.
    Parameters:   lng - longitude value to check.
                         start - this is the start position of the range in longitude degrees
                         end - this is the end position of the range in longitude degrees
    Returns:  true if the provided longitude is within the specified range, false otherwise.
    Example: isInRange(30.0, 20.0, 40.0); //this call will return true since 30.0 degrees position is within the 20-40 degrees range.
   


Static values:

    House Systems:
     Zodiac and  Ayanamsa:
    Coordinates System:

   Constants to access objects/planets information in XML:

    Constants for chart Styles:

    Constants to set the Language:




Editions: