Module: nationscript/api

The entry point to any NationScript usage.

It contains several functions for changing settings of NationScript:

  • setAgent() for setting the mandatory custom user agent,
  • setUseRateLimit() for en-/disabling the built-in rate-limiter of NationScript,
  • setUseVersion() to specify a specific API version to make all calls to,
  • setTGClientKey() to set the client key to use for TG API requests,
  • setDumpDirectory() to set a custom directory to save local Data Dump copies in.

It furthermore provides a variety of functions that return new instances of the request subclass fine-tuned for building queries to the corresponding API endpoint. A basic request instance for more low-level request building can also be instantiated using the custom() function. The specialised instantiation functions are:

  • For the reading endpoints:
    • nation()
    • region()
    • world()
    • wa()
    • cardDetails()
    • cards()
  • For command endpoints:
    • issue()
    • giftCard()
    • dispatchAdd()
    • dispatchEdit()
    • dispatchRemove()
    • rmb()
  • For the miscellaneous endpoints:
    • tg()
    • ua()
    • v()
  • For querying Data Dumps:
    • nationsFromDump()
    • regionsFromDump()
    • cardsFromDump()

Methods

(inner) cardDetails(cardID, season) → {CardIndividualRequest}

Request data about an individual trading card from the API!

Parameters:
Name Type Description
cardID number

ID of the desired card
season number

Number of the season the desired card was inscribed for
Returns:
Type
CardIndividualRequest

(inner) cards() → {CardWorldRequest}

Request data about the wider world of trading cards from the API!

Returns:
Type
CardWorldRequest

(inner) cardsFromDump(mode, season) → {CardDumpRequest}

Get data on a large number of trading cards using the cards Data Dump!

Parameters:
Name Type Default Description
mode number

DumpMode to use
season number 3

ID of the desired trading cards season; defaults to 3
Returns:
Type
CardDumpRequest

(inner) custom() → {DataRequest}

Build a request to the NS API completely from scratch!

Returns:
Type
DataRequest

(inner) dispatchAdd(credentialsopt) → {DispatchAddCommand}

Have a nation publish a new dispatch!

Parameters:
Name Type Attributes Description
credentials NSCredential <optional>

Login credentials for the nation to use
Returns:
Type
DispatchAddCommand

(inner) dispatchEdit(credentialsopt) → {DispatchEditCommand}

Have a nation edit one of its existing dispatches!

Parameters:
Name Type Attributes Description
credentials NSCredential <optional>

Login credentials for the nation to use
Returns:
Type
DispatchEditCommand

(inner) dispatchRemove(credentialsopt) → {DispatchDeleteCommand}

Have a nation delete one of its existing dispatches!

Parameters:
Name Type Attributes Description
credentials NSCredential <optional>

Login credentials for the nation to use
Returns:
Type
DispatchDeleteCommand

(inner) giftCard(credentialsopt) → {GiftCardCommand}

Have a nation gift a trading card to another nation!

Parameters:
Name Type Attributes Description
credentials NSCredential <optional>

Login credentials for the nation to use
Returns:
Type
GiftCardCommand

(inner) issue(credentialsopt) → {IssueCommand}

Have a nation address the specified issue!

Parameters:
Name Type Attributes Description
credentials NSCredential <optional>

Login credentials for the nation to use
Returns:
Type
IssueCommand

(inner) nation(name) → {NationRequest}

Request data about a single nation from the API!

Parameters:
Name Type Description
name string

Name of the nation to request data on
Returns:
Type
NationRequest

(inner) nationsFromDump(mode, date) → {NationDumpRequest}

Get data on a large number of nations using the nations Daily Data Dump!

Parameters:
Name Type Description
mode number

DumpMode to use
date Date

Date of the desired Dump ;defaults to the most recent one
Returns:
Type
NationDumpRequest

(inner) region(name) → {RegionRequest}

Request data about a single region from the API!

Parameters:
Name Type Description
name string

Name of the region to request data on
Returns:
Type
RegionRequest

(inner) regionsFromDump(mode, date) → {RegionDumpRequest}

Get data on a large number of regions using the regions Daily Data Dump!

Parameters:
Name Type Description
mode number

DumpMode to use
date Date

Date of the desired Dump; defaults to the most recent one
Returns:
Type
RegionDumpRequest

(inner) rmb(credentialsopt) → {RMBPostCommand}

Have a nation lodge a message to the Regional Message Board of a region!

Parameters:
Name Type Attributes Description
credentials NSCredential <optional>

Login credentials for the nation to use
Returns:
Type
RMBPostCommand

(inner) setAgent(agent)

Registers the custom part of the user agent for this script, which will be sent as the User-Agent header together with a notice that the request is being made using this library in all HTTP requests to the NS API.

Setting a UserAgent is mandatory per the Terms of Use of the NS API. As long as it's not deceptive and allows NS staff to contact you in case something goes wrong, there are no specific requirements for it.

Parameters:
Name Type Description
agent string

The string to send as user agent.

(inner) setDumpDirectory(path)

Registers a custom directory to save and look for local Daily Data Dump copies in.

Parameters:
Name Type Description
path string

Path to the desired save directory.

(inner) setDumpNameCard(fileNamer)

Register a custom way to determine the file names of local copies of the Cards Seasonal Data Dump.

Parameters:
Name Type Description
fileNamer dump.FileNamerCard

Function determining the file name, depending on a given season number

(inner) setDumpNameNation(fileNamer)

Register a custom way to determine the file names of local copies of the Nations Daily Data Dump.

Parameters:
Name Type Description
fileNamer dump.FileNamerNormal

Function determining the file name, depending on a given Date

(inner) setDumpNameRegion(fileNamer)

Register a custom way to determine the file names of local copies of the Regions Daily Data Dump.

Parameters:
Name Type Description
fileNamer dump.FileNamerNormal

Function determining the file name, depending on a given Date

(inner) setTGClientKey(key)

Registers the telegram client key to use for TGRequests. Unlike the rest of the NS API, sending TGs requires a special client key issued by moderator.

Parameters:
Name Type Description
key string

The client key to use.

(inner) setUseRateLimit(state)

Enables or disables the built-in automatic rate-limiting function of NationScript. Useful if you want to use a custom, slower rate of sending requests, or have other programs making requests to the NS API that aren't run by this NationScript instance. Enabled by default.

Parameters:
Name Type Description
state boolean

true to use built-in rate-limiter, false to disable it.

(inner) setUseVersion(versionnullable)

Registers a custom NS API version to use with all requests. The API supports the two most recent versions; the current version number can be checked via the API itself using this link or a VersionRequest.

Parameters:
Name Type Attributes Description
version number <nullable>

API version to request the data in; null to use the most recent.

(inner) tg(recipient) → {TGRequest}

Send a telegram to the specified nation!

Parameters:
Name Type Description
recipient string

Name of the nation that should receive the telegram
Returns:
Type
TGRequest

(inner) ua() → {UserAgentRequest}

Check how the user agent you set appears to the NS API!

Returns:
Type
UserAgentRequest

(inner) v() → {VersionRequest}

Check the current version of the NS API!

Returns:
Type
VersionRequest

(inner) wa(council) → {WARequest}

Request data about the World Assembly from the API!

Parameters:
Name Type Description
council number

ID of the WA council the data should be about
See:
  • WACouncil for valid council IDs.
Returns:
Type
WARequest

(inner) world() → {WorldRequest}

Request data about the wider game world from the API!

Returns:
Type
WorldRequest