Package: nodeping-api
python-nodeping-apiA Python2/3 library for managing checks, schedules, and contactsTable of Contentspython-nodeping-apiGeneral UsageInstallationVerify API tokenChecking validitySample CodeRetrieving Account InfoChecksGet ChecksCreate ChecksUpdate ChecksUpdating oneUpdating manyDisable ChecksDisable by LabelDisable by TargetDisable by TypeDisable AllDelete ChecksContactsGetting ContactsGet All ContactsGet a Single ContactGet Contacts by TypeCreate a ContactUpdate a ContactDelete a ContactResetting a PasswordContact GroupsGet GroupsCreate GroupsUpdate GroupDelete GroupSchedulesGet SchedulesCreate SchedulesUpdate SchedulesDelete SchedulesMaintenanceGet MaintenanceCreate MaintenanceUpdate MaintenanceDelete MaintenanceNotificationsNotification ExamplesResultsGetting Check ResultsGet UptimeGetting Monthly Uptime Since 2019-02Getting Daily Uptime In Time RangeCurrent EventsInformationGet Probe InfoGet NY Probe InfoGet Location InformationGet North America InfoDiagnosticsInitiate an MTRDo a DNS LookupGeneral UsageTo use the NodePing API with Python2/3, you are required to use your
provided API token. You can find your API key on your NodePing account
underAccount Settings → API.You can also optionally provide a Sub Account ID which can be found
underAccount Settings → SubAccountsand you will see the ID by its
name.You can set these variables, for example, like so:token='my-api-token'customerid='your-subaccount-id'InstallationTo install this package, run:pip install nodeping-apiVerify API tokenThis module lets you check if your token is valid and return info about
your account.Checking validityThe name of this function isis_valid()This simply returnsTrueor raises an exception if the key is not
valid.Sample Code>>>fromnodeping_apiimportcheck_token>>>valid_token=check_token.is_valid(token)>>>print(valid_token)TrueOr if your key is invalid>>>valid_token=check_token.is_valid(token)FalseRetrieving Account InfoThe name of this function isinfo()This will return the contents from NodePing in a dictionary format. If
the token isn’t valid, nothing will be returned.Example:fromnodeping_apiimportcheck_tokeninfo=check_token.info(token)This will return basic information about your account. Optionally, you
can do the same with a subaccount:fromnodeping_apiimportcheck_tokensubacc_info=check_token.info(token,customerid=customerid)ChecksGet ChecksGet checks on your NodePing account via theget_checks.pymodule.This module will get all checks that are specified, whether enabled or
disabled (excludingdisabled_checks(), which will only get disabled
checks)Lets you gather:All checksPassing checksFailing checksDisabled checksLast resultGetting check info examples:fromnodeping_apiimportget_checks# Optionally set customerid to your subaccount IDquery_nodeping=get_checks.GetChecks(token)# Get all checksall=query_nodeping.all_checks()# Get passing checkspassing=query_nodeping.passing_checks()# Get failing checksfailing=query_nodeping.failing_checks()# Get disabled checksdisabled=query_nodeping.disabled_checks()# Get last resultlast=query_nodeping.last_result()# Get check by IDquery_nodeping=get_checks.GetChecks(token,checkid=_id)check=query_nodeping.get_by_id()Create ChecksCreate checks on your NodePing account via thecreate_check.pymodule.This module lets you create a check of any type and with your specified
parameters.Example of creating an HTTP check:defhttp():contacts=[{"contactkey":{"delay":0,"schedule":"Days"}}]loc="NAM"webserver="https://example.com"result=create_check.http_check(token,webserver,label="http example.com",enabled=True,follow=True,runlocations=loc,notifications=contacts)pprint(result)Example of creating a PUSH check:defpush(token,contacts,region):fields={"apcupsd":{"name":"apcupsd","min":1,"max":1},"load1min":{"name":"load.1min","min":"0","max":"4"},"load5min":{"name":"load.5min","min":"0","max":"2"},"memavail":{"name":"memavail","min":"100","max":"10000"}}results=create_check.push_check(token,label="Test PUSH",fields=fields,interval=1,runlocations=region,notifications=contacts)pprint(results)Update ChecksUpdate checks on your NodePing account via theupdate_checks.pymodule.This module lets you update one or many checks at once. To upate one
check, you will have to supply the Check ID, the type of check, and the fields you want to
change. To update many, you will have to create a dict of Check IDs.Updating onefromnodeping_apiimportupdate_checkscheckid='201205050153W2Q4C-0J2HSIRF'checktype='PING'fields={"public":False,"interval":15}data=update_checks.update(token,checkid,checktype,fields)The returned data will be the information about the check (with updated
values) in a dictionary format.Updating manyfromnodeping_apiimportupdate_checkscheckids={'201205050153W2Q4C-0J2HSIRF':'PING','201205050153W2Q4C-4RZT8MLN':'HTTP'}fields={"public":False,"interval":15}data=update_checks.update_many(token,checkids,fields)The returned data will be the information about the checks (with updated
values) in a dictionary format.Disable ChecksDisable checks on your NodePing account via thedisable_check.pymodule.This module lets you disable checks in various ways:By labelBy targetBy typeAllThis will not disable checks on subaccounts.Set disable to True to disable checks, False to enable. Checks will only
be enabled if they have been disabled via this method.https://nodeping.com/docs-api-checks.html#disableallDisable by LabelSpecify the label of the check to be enabled/disabledfromnodeping_apiimportdisable_checklabel="I dont need this"# Disables the checkdisable_check.disable_by_label(token,label,disable=True)Disable by TargetSpecify the Check ID of the check to be enabled/disabledfromnodeping_apiimportdisable_checkcheckid='201205050153W2Q4C-0J2HSIRF'# Disables the check by IDdisable_check.disable_by_target(token,checkid,disable=True)Disable by TypeSpecify the TYPE of checks to be disabled (such as PING checks)fromnodeping_apiimportdisable_check_type='PING'# Disables the checks by type PINGdisable_check.disable_by_type(token,_type,disable=True)Disable AllThis disables all checks on the accountfromnodeping_apiimportdisable_check# Disables the checks by type PINGdisable_check.disable_all(token,disable=True)# Disable all checks on subaccountdisable_check.disable_all(token,disable=True,customerid=subacc)Delete ChecksDelete checks on your NodePing account via thedelete_check.pymodule.This module will only remove checks one at a time by supplying your
Check ID.Example:fromnodeping_apiimportdelete_checkscheckid='201205050153W2Q4C-0J2HSIRF'data=delete_checks.remove(token,checkid)Sample data returned:{'ok': True, 'id': '201205050153W2Q4C-0J2HSIRF'}Or if the check does not exist:{'error': 'Unable to find that check'}ContactsGetting ContactsGet contacts on your NodePing account via thecontacts.pymodule.This module allows you to get all contacts on your account, get a single
contact, or get by type such as sms, email, webhook.Get All Contactsfromnodeping_apiimportcontactsall_contacts=contacts.get_all(token)Sample data returned:{
  "201205050153W2Q4C-BKPGH": {
    "_id": "201205050153W2Q4C-BKPGH",
    "type": "contact",
    "customer_id": "201205050153W2Q4C",
    "name": "Foo Bar",
    "custrole": "owner",
    "addresses": {
      "K5SP9CQP": {
        "address": "foo@example.com",
        "status": "new"
      }
    }
  }
}When providing contacts for creating checks, theK5SP9CQPin this
example is the contact id you will need.Get a Single Contactfromnodeping_apiimportcontactsall_contacts=contacts.get_one(token,'201205050153W2Q4C-BKPGH')Sample data returned:{
  "201205050153W2Q4C-BKPGH": {
    "_id": "201205050153W2Q4C-BKPGH",
    "type": "contact",
    "customer_id": "201205050153W2Q4C",
    "name": "Foo Bar",
    "custrole": "owner",
    "addresses": {
      "K5SP9CQP": {
        "address": "foo@example.com",
        "status": "new"
      }
    }
  }
}Get Contacts by Typefromnodeping_apiimportcontactscontact_type='sms'contacts_by_type=contacts.get_by_type(token,contact_type)Create a ContactCreate a new contact on your account. When creating an account, supply the name,
custrole (such as if they have view permissions or owner), and the addresses that
contact will use.>>>fromnodeping_apiimportcontacts>>>frompprintimportpprint>>>token='my-api-token'>>>newaddresses=[{'address':'me@example.com','type':'email'},{'address':'me2@example.com','type':'pagerduty'},{'address':'1235558888','type':'sms'}]>>>name="my new contact">>>new_contact=contacts.create_contact(token,name=name,newaddresses=newaddresses)pprint(new_contact){'_id':'2019052211307H0IX-KR9CO','addresses':{'JMMARFHQ':{'accountsuppressall':false,'type':'email','address':'me2@example.com'},'NMYW1XC1':{'accountsuppressall':false,'type':'pagerduty','address':'me@example.com'},'P080YGYO':{'accountsuppressall':false,type': 'sms','address':'1235558888'}},'customer_id':'2019052211307H0IX','custrole':'view','name':'my new contact','sdomain':'nodeping.com','type':'contact'}Update a ContactYou can also update existing created contacts based on their contact ID. You can
change its name, role, add contact addresses, or modify existing ones. Note that
when you are modifying existing contacts, you must supply the entire list of
contacts for that user. Missing entries will be removed.In the example below, the updated contact is exactly the same as the contact
in the create contact example, but with the addresses updated as well as some
new addresses added.https://nodeping.com/docs-api-contacts.html>>>fromnodeping_apiimportcontacts>>>frompprintimportpprint>>>token='my-api-token'>>>contact_id="2019052211307H0IX-KR9CO">>>newaddresses=[{'address':'me@example.com'},{'address':'me2@example.com'},{'address':'1235558888'}]>>>addresses={'JMMARFHQ':{'address':'newme@example.com','accountsupressall':False},'NMYW1XC1':{'address':'newme2@example.com','accountsupressall':False},'P080YGYO':{'address':'321444777','accountsuppressall':False}}>>>pprint(contacts.update_contact(token,contact_id,addresses=addresses,newaddresses=newaddresses)){'_id':'2019052211307H0IX-KR9CO','addresses':{'8XK9OGNW':{'accountsuppressall':False,'address':'me2@example.com'},'CUSR6CTF':{'accountsuppressall':False,'address':'me@example.com'},'JMMARFHQ':{'accountsuppressall':False,'address':'newme@example.com'},'NMYW1XC1':{'accountsuppressall':False,'address':'newme2@example.com'},'P080YGYO':{'accountsuppressall':False,'address':'321444777'},'VZ5HY05B':{'accountsuppressall':False,'address':'1235558888'}},'customer_id':'2019052211307H0IX','custrole':'view','name':'my new contact','sdomain':'nodeping.com','type':'contact'}Delete a ContactIf you no longer need a contact, you can simply delete it by specifying its IDfromnodeping_apiimportcontactsfrompprintimportpprinttoken='my-api-token'contact_id="2019052211307H0IX-KR9CO"deleted=contacts.delete_contact(token,contact_id)With the resulting output:{'id':'2019052211307H0IX-KR9CO','ok':True}Resetting a PasswordYou can reset passwords for a contact by specifying their contact ID:fromnodeping_apiimportcontactstoken='my-api-token'contact_id='2019052211307H0IX-KR9CO'reset='contacts.reset_password(token, contact_id)This will send a new password to the email address associated with that contact.Contact GroupsManage contact groups on your NodePing account via thegroup_contacts.pymodule.https://nodeping.com/docs-api-contactgroups.htmlThis module lets you manage contact groups in these ways:Get contact groupsCreate contact groupsUpdate contact groupsDelete contact groupsGet Groupsfromnodeping_apiimportgroup_contacts# Get contact groupsgroups=group_contacts.get_all(token)# Get contact groups with SubAccount IDsubaccount_id="your-subaccount-id"groups=group_contacts.get_all(token,customerid=subaccount_id)Create GroupsTo create a contact group, a name for the group is required. You can optionally
provide members for the contact group in a list. The member will be the key in
the addresses field for each contact. For example, if your contact data is this:{
      "201205050153W2Q4C-BKPGH": {
        "_id": "201205050153W2Q4C-BKPGH",
        "type": "contact",
        "customer_id": "201205050153W2Q4C",
        "name": "Foo Bar",
        "custrole": "owner",
        "addresses": {
          "K5SP9CQP": {
            "address": "foo@example.com",
            "status": "new"
          }
        }
      }
    }Then the contact ID you need is "K5SP9CQP".Example:fromnodeping_apiimportgroup_contactsname="sample_group"my_members=["K5SP9CQP","D3RF9NQT"]# Create group without membersempty_group=group_contacts.create_group(token,name)# Create group with membersnew_group=group_contacts.create_group(token,name,members=my_members)Update GroupUpdating the group is the same idea as creating a group.Example:fromnodeping_apiimportgroup_contactsname="sample_group"new_name="renamed"my_members=["K5SP9CQP","D3RF9NQT"]# Update group with new membersupdated_group=group_contacts.update_group(token,name,members=my_members)# Rename a grouprenamed=group_contacts.update_group(token,new_name)Delete GroupTo delete the group, you need to provide the group id, which can be found
when you get the groups.Example:fromnodeping_apiimportgroup_contactsgroup_id="201205050153W2Q4C-G-1ZIYU"# Delete the groupdeleted=group_contacts.delete_group(token,group_id)This will return a dictionary stating that the group was deleted:{'id': '201205050153W2Q4C-G-1ZIYU', 'ok': True}If it failed, a dictionary with the key error will be gathered.SchedulesManage schedules on your NodePing account via theschedules.pymodule.https://nodeping.com/docs-api-schedules.htmlThis module lets you manage checks in these ways:Get schedulesCreate schedulesUpdate schedulesDelete schedulesGet Schedulesfromnodeping_apiimportschedules# Get all schedulesschedules=schedules.get_schedules(token)# Get schedule by nameweekend_schedule=schedules.get_schedules(token,schedule="Weekends")Create SchedulesTo create a schedule, you need to provide data for each day and what its
schedule will be like.fromnodeping_apiimportschedulesdata={'data':{'friday':{'exclude':False,'time1':'8:00','time2':'23:00'},'monday':{'allday':True},'saturday':{'exclude':False,'time1':'6:00','time2':'18:00'},'sunday':{'disabled':True},'thursday':{'exclude':False,'time1':'8:00','time2':'22:00'},'tuesday':{'disabled':True},'wednesday':{'exclude':True,'time1':'18:30','time2':'20:30'}}}schedule_name='myschedule'created=schedules.create_schedule(token,data,schedule_name)Update SchedulesUpdating schedules lets you update an entire day or a portion of itfromnodeping_apiimportschedulesdata={'data':{'saturday':{'exclude':False,'time1':'6:00','time2':'18:00'},}}schedule_name='myschedule'updated=schedules.update_schedule(token,data,schedule_name)Delete SchedulesTo delete a schedule, just provide its namefromnodeping_apiimportschedulesschedule_name='myschedule'deleted=schedules.delete_schedule(token,schedule)MaintenanceManage maintenances for your NodePing account via themaintenance.pymodule.Get, create, update, and delete maintenances as well as create ad-hoc
maintenance schedules.Get MaintenanceYou can get maintenances by id or all at oncefromnodeping_apiimportmaintenancetoken="my-api-token"maintenanceid="NZT101"# Get maintenanceall_maintenance=maintenance.get_maintenance(token,maintenanceid=maintenanceid)# Get all maintenancesone_maintenance=maintenance.get_maintenance(token)Create MaintenanceCreate scheduled maintenances or an ad-hoc maintenancefromnodeping_apiimportmaintenancetoken="my-api-token"cron="1 12 * * *"duration=30name="my_maintenance"checklist=["201911191441YC6SJ-4S9OJ78G","201911191441YC6SJ-XB5HUTG6"]# Create ad-hoc maintenancead_hoc=maintenance.create_maintenance(token,duration,checklist,name=name,_id="ad-hoc")# Create scheduled maintenancescheduled=maintenance.create_maintenance(token,duration,checklist,name=name,enabled=True,cron=cron)Update MaintenanceUpdate existing scheduled maintenancesfromnodeping_apiimportmaintenancetoken="my-api-token"duration="45"name="new name for schedule"_id="NZT101"checklist=["201911191441YC6SJ-4S9OJ78G","201911191441YC6SJ-XB5HUTG6"]result=maintenance.update_maintenance(token,_id,duration,checklist,name=name)Delete MaintenanceDelete an existing scheduled maintenancefromnodeping_apiimportmaintenancetoken="my-api-token"_id="NZT101"deleted=maintenance.delete_maintenance(token,_id)NotificationsGet notifications for your NodePing account via thenotifications.pymodule.When getting notifications, you can limit how many you get by the number of hours,
number of notifications, if you want to collect from subaccounts or not, and by
check IDNotification ExamplesGetting the last 100fromnodeping_apiimportnotificationstoken='my-api-tokenlimit=100last_notifications=notifications.get_notifications(token,limit=limit)Getting results for a check ID for the last 2 hoursfromnodeping_apiimportnotificationstoken="my-api-token"span=2check_id='201205050153W2Q4C-0J2HSIRF'last_notifications=notifications.get_notifications(token,check_id=check_id,span=span)ResultsThis module lets you get results and uptime for different checks at optionally given
time durations. To get an idea of what the output will look like from the API, you
can visit the documentation that shows what outputs you will get:https://nodeping.com/docs-api-results.htmlGetting Check ResultsGet the last 100 results for a check.fromnodeping_apiimportresultstoken='my-api-tokencheck_id='201205050153W2Q4C-0J2HSIRF'limit=100last_results=results.get_results(token,check_id,limit=limit)Your output will consist of a list of dictionaries that will look like this:[{"_id":"201205050153W2Q4C-0J2HSIRF-1345313038648","ci":"201205050153W2Q4C","t":"DNS","tg":"8.8.8.8","th":"5","i":"5","ra":"1345313029252","q":"caRRa3op0v","s":1345313038648,"sc":"Success","su":true,"rt":77,"e":1345313038725,"l":{"1345313038648":"ca"}}]Get UptimeThis lets you get the uptime percentages for the specified check. The output
will be a dictionary of the last days/months and their uptime and downtime.Getting Monthly Uptime Since 2019-02With the API, monthly is the default interval, so you do not need to
specify "monthly" unless you want to.fromnodeping_apiimportresultsfrompprintimportpprinttoken='my-api-tokencheck_id='201205050153W2Q4C-0J2HSIRF'pprint(results.get_uptime(token,check_id,start="2019-02"))With the output:{'2019-02':{'down':2808090,'enabled':2419200000,'uptime':99.884},'2019-03':{'down':41679682,'enabled':2678398201,'uptime':98.444},'2019-04':{'down':4511825,'enabled':2592000000,'uptime':99.826},'2019-05':{'down':764817,'enabled':2678359942,'uptime':99.971},'2019-06':{'down':5762929,'enabled':2592000000,'uptime':99.778},'2019-07':{'down':3585847,'enabled':2661778859,'uptime':99.865},'total':{'down':59113190,'enabled':15621737002,'uptime':99.622}}Getting Daily Uptime In Time RangeYou can also get daily results on uptime. In addition to that, you can
specify the start/end dates. In this case, we will start on
2019-07-01 and collect to 2019-07-15fromnodeping_apiimportresultsfrompprintimportpprinttoken='my-api-tokencheck_id='201205050153W2Q4C-0J2HSIRF'start="2019-07-01"end="2019-07-25"pprint(results.get_uptime(token,check_id,interval="days",start=start,end=end))With the output:{'2019-07-01':{'down':0,'enabled':86400000,'uptime':100},'2019-07-02':{'down':0,'enabled':86400000,'uptime':100},'2019-07-03':{'down':0,'enabled':86400000,'uptime':100},'2019-07-04':{'down':0,'enabled':86400000,'uptime':100},'2019-07-05':{'down':140740,'enabled':86400000,'uptime':99.837},'2019-07-06':{'down':417545,'enabled':86400000,'uptime':99.517},'2019-07-07':{'down':0,'enabled':86400000,'uptime':100},'2019-07-08':{'down':144979,'enabled':86400000,'uptime':99.832},'2019-07-09':{'down':0,'enabled':86400000,'uptime':100},'2019-07-10':{'down':0,'enabled':86400000,'uptime':100},'2019-07-11':{'down':0,'enabled':86400000,'uptime':100},'2019-07-12':{'down':699479,'enabled':86400000,'uptime':99.19},'2019-07-13':{'down':0,'enabled':86400000,'uptime':100},'2019-07-14':{'down':0,'enabled':86400000,'uptime':100},'total':{'down':1402743,'enabled':1209600000,'uptime':99.884}}Note that all the results you get will also have a total downtime
for that give time range.Current EventsRetrieves information about current "events" for checks. Events include down events
and disabled checks. If you need a list of all checks with their passing/failing
state, please use the 'checks' list rather than this 'current' call.fromnodeping_apiimportresultstoken='my-api-tokencurrent=results.get_current(token)InformationGet probe and location information via theinformation.pymodule.Get Probe InfoYou can get information about all probes or a specific probe.
This information mirrors what is available on our FAQ:https://nodeping.com/faq.html#ip-addressesGet NY Probe Infofromnodeping_apiimportinformationfrompprintimportpprinttoken='my-api-token'probe="ny"ny_probe=information.get_probe(token,probe=probe)With the output:{'country':'US','ipv4':'66.23.202.26','ipv6':'2605:9f80:c000:127::2','location':'ny','locationname':'New York City, New York','region':'nam','regionname':'North America'}Get Location InformationWith this function, you can get all probe information oa
information about probes in a region.Get North America Infofromnodeping_apiimportinformationfrompprintimportpprinttoken='my-api-token'location='nam'nam_location=information.get_location(token,location=location)With the output:{'locations':['il','tx','nj','ga','ca','co','wa','ny','py','oh','ut','or','fl'],'regionname':'North America'}DiagnosticsRequest diagnostic information from a probe or AGENT via thediagnostics.pymodule.Find more information on the diagnostics functionalityhereand more information about the diagnostics toolhere.Initiate an MTRfromnodeping_apiimportdiagnosticstoken='my-api-token'checkid='my-check-id'location='ny'tool='mtr'# If target not specified, the target will be taken from the check datatarget='example.com'count=25result=diagnostics.get(token,checkid,location,tool,target=target,count=count)This will run an MTR and return the output in a dictionary format.Do a DNS Lookupfromnodeping_apiimportdiagnosticstoken='my-api-token'checkid='my-check-id'location='ny'tool='dig'target='example.com'dnstype='AAAA'result=diagnostics.get(token,checkid,location,tool,target=target,dnstype=dnstype)