├── .gitignore ├── LICENSE ├── README.md ├── demo.js ├── index.js ├── package-lock.json └── package.json /.gitignore: -------------------------------------------------------------------------------- 1 | node_modules 2 | test.js -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | MIT License 2 | 3 | Copyright (c) 2019 BigDataCloud 4 | 5 | Permission is hereby granted, free of charge, to any person obtaining a copy 6 | of this software and associated documentation files (the "Software"), to deal 7 | in the Software without restriction, including without limitation the rights 8 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 9 | copies of the Software, and to permit persons to whom the Software is 10 | furnished to do so, subject to the following conditions: 11 | 12 | The above copyright notice and this permission notice shall be included in all 13 | copies or substantial portions of the Software. 14 | 15 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 16 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 17 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 18 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 19 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 20 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE 21 | SOFTWARE. 22 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # BigDataCloud NodeJS API Client 2 | 3 | 4 | A NodeJS client for connecting to the API services provided by [BigDataCloud](https://www.bigdatacloud.com). 5 | 6 | 7 | ## What API services does [BigDataCloud](https://www.bigdatacloud.com) offer? 8 | 9 | BigDataCloud offers a range of extremely useful and fast APIs that can be utilised in both backend and frontend scenarios. 10 | From validating customer input live to the next generation of IP Geolocation technology, BigDataCloud has an API suitable to your needs. 11 | 12 | You can access any and all BigDataCloud APIs with a free API Key. 13 | To get your API Key, just access your account and retrieve it from your [Account Dashboard](https://www.bigdatacloud.com/account). 14 | 15 | If you are not yet a customer, it is completely free to join. 16 | 17 | ### BigDataCloud API Packages 18 | 19 | All BigDataCloud APIs are bundled into five different API packages. Each API package has its own subscription plans and pricings. 20 | 21 | You can find more details on the respective API packages page. 22 | - [IP Geolocation Package](https://www.bigdatacloud.com/ip-geolocation) 23 | - [Reverse Geocoding Package](https://www.bigdatacloud.com/reverse-geocoding) 24 | - [Phone & Email Verification Package](https://www.bigdatacloud.com/phone-email-verification) 25 | - [Network Engineering Package](https://www.bigdatacloud.com/network-engineering), and 26 | - [Free API Package](https://www.bigdatacloud.com/free-api) (doesn't require account creation and API key) 27 | 28 | ## Documentation 29 | 30 | For documentation specific to this api client, please read below. 31 | For more specific documentation to the APIs available, including endpoints, request and response data, please visit the respective API package page. 32 | 33 | 34 | ## Update Notes 35 | 36 | - This repository now utilises `node-fetch` rather than the deprecated `request` module. 37 | - Calls to the API will return a JSON object as a successful response, see below for an example 38 | - Exceptions return a single object: `{error:json_object || error_string,code:http_status_code}` 39 | 40 | 41 | 42 | ## Authentication / Identification 43 | 44 | To use this API client you must have a BigDataCloud API Key. 45 | To get your personal key, just access your account and retrieve it from your [Account Dashboard](https://www.bigdatacloud.com/account). 46 | If you are not yet a customer, it is completely free to join. 47 | 48 | Simply provide this key when initiating the api client, and it will be included in all requests to the BigDataCloud API Server. 49 | See the example below. 50 | 51 | 52 | 53 | ## Installation 54 | 55 | `npm install @bigdatacloudapi/client` 56 | 57 | 58 | 59 | ## Example usage 60 | 61 | The below example is found in the included demo.js. 62 | 63 | ```javascript 64 | const client = require('@bigdatacloudapi/client')('XXX'); // XXX being your api key found at: https://www.bigdatacloud.com/account 65 | 66 | /* 67 | * All api endpoints can be accessed via magic methods in the following camelised format: 68 | * method | endpoint 69 | * For example: an asynchronous "GET" call to the "ip-geolocation-full" endpoint would be: client.getIpGeolocationFull(); 70 | * All endpoints return a promise 71 | */ 72 | 73 | //Asynchronous example using 'then': 74 | client 75 | .getIpGeolocationFull({ip:'8.8.8.8'}) 76 | .then(jsonResult=> { 77 | console.log('Asynchronous "then" result:',jsonResult); 78 | }) 79 | .catch(function(error) { 80 | console.error('Asynchronous "then" error:', error); 81 | }); 82 | 83 | //Asynchronous example using 'await': 84 | (async function() { 85 | try { 86 | var jsonResult = await client.getIpGeolocationFull({ip:'8.8.8.8'}); 87 | console.log('Asynchronous "await" result:',jsonResult); 88 | } catch (error) { 89 | console.error('Asynchronous "await" error:', error); 90 | } 91 | })(); 92 | 93 | ``` 94 | 95 | 96 | ## Example output 97 | 98 | ```javascript 99 | { 100 | "ip": "8.8.8.8", 101 | "country": { 102 | "isoAlpha2": "US", 103 | "isoAlpha3": "USA", 104 | "m49Code": 840, 105 | "isoName": "United States of America (the)", 106 | "isoAdminLanguages": [ 107 | { 108 | "isoAlpha3": "eng", 109 | "isoAlpha2": "en", 110 | "isoName": "English" 111 | } 112 | ], 113 | "unRegion": "Americas/Northern America", 114 | "currency": { 115 | "numericCode": 840, 116 | "code": "USD", 117 | "name": "US Dollar", 118 | "minorUnits": 2 119 | }, 120 | "wbRegion": { 121 | "id": "NAC", 122 | "iso2Code": "XU", 123 | "value": "North America" 124 | }, 125 | "wbIncomeLevel": { 126 | "id": "HIC", 127 | "iso2Code": "XD", 128 | "value": "High income" 129 | }, 130 | "callingCode": "1", 131 | "countryFlagEmoji": "🇺🇸" 132 | }, 133 | "location": { 134 | "isoPrincipalSubdivision": "California", 135 | "isoPrincipalSubdivisionCode": "US-CA", 136 | "city": "Mountain View", 137 | "postcode": "94043", 138 | "latitude": 37.42, 139 | "longitude": -122.09, 140 | "timeZone": { 141 | "ianaTimeId": "America/Los_Angeles", 142 | "displayName": "(UTC-08:00) Pacific Time (US & Canada)", 143 | "effectiveTimeZoneFull": "Pacific Daylight Time", 144 | "effectiveTimeZoneShort": "PDT", 145 | "UtcOffsetSeconds": -25200, 146 | "UtcOffset": "-07", 147 | "isDaylightSavingTime": true, 148 | "localTime": "2019-04-06T04:06:39.1691744" 149 | } 150 | }, 151 | "lastUpdated": "2019-04-06T09:09:36.1877959Z", 152 | "network": { 153 | "registry": "ARIN", 154 | "registryStatus": "assigned", 155 | "registeredCountry": "US", 156 | "registeredCountryName": "United States of America (the)", 157 | "organisation": "Google LLC", 158 | "isReachableGlobally": true, 159 | "isBogon": false, 160 | "bgpPrefix": "8.8.8.0/24", 161 | "bgpPrefixNetworkAddress": "8.8.8.0", 162 | "bgpPrefixLastAddress": "8.8.8.255", 163 | "totalAddresses": 256, 164 | "carriers": [ 165 | { 166 | "asn": "AS15169", 167 | "asnNumeric": 15169, 168 | "organisation": "Google LLC", 169 | "name": "GOOGLE", 170 | "registry": "ARIN", 171 | "registeredCountry": "US", 172 | "registeredCountryName": "United States of America (the)", 173 | "registrationDate": "2000-03-30", 174 | "registrationLastChange": "2012-02-25", 175 | "totalIpv4Addresses": 8698103, 176 | "totalIpv4Prefixes": 435, 177 | "totalIpv4BogonPrefixes": 0, 178 | "rank": 53, 179 | "rankText": "#53 out of 62,872" 180 | } 181 | ], 182 | "viaCarriers": [ 183 | { 184 | "asn": "AS7018", 185 | "asnNumeric": 7018, 186 | "organisation": "ATT Services Inc.", 187 | "registeredCountry": "US", 188 | "registeredCountryName": "United States of America (the)", 189 | "rank": 2 190 | }, 191 | /*........*/ 192 | { 193 | "asn": "AS31019", 194 | "asnNumeric": 31019, 195 | "organisation": "Paulus M. Hoogsteder trading as Meanie", 196 | "registeredCountry": "NL", 197 | "registeredCountryName": "Netherlands (the)", 198 | "rank": 51153 199 | } 200 | ] 201 | }, 202 | "confidence": "low", 203 | "confidenceArea": [ 204 | { 205 | "latitude": 18.0256672, 206 | "longitude": -66.5275345 207 | }, 208 | /*........*/ 209 | { 210 | "latitude": 18.0256672, 211 | "longitude": -66.5275345 212 | } 213 | ], 214 | "securityThreat": "unknown", 215 | "hazardReport": { 216 | "isKnownAsTorServer": false, 217 | "isKnownAsVpn": false, 218 | "isKnownAsProxy": false, 219 | "isSpamhausDrop": false, 220 | "isSpamhausEdrop": false, 221 | "isSpamhausAsnDrop": false, 222 | "isBlacklistedUceprotect": false, 223 | "isBlacklistedBlocklistDe": false, 224 | "isKnownAsMailServer": false, 225 | "isKnownAsPublicRouter": false, 226 | "isBogon": false, 227 | "isUnreachable": false, 228 | "hostingLikelihood": 0, 229 | "isHostingAsn": false, 230 | "isCellular": false, 231 | "iCloudPrivateRelay": false 232 | } 233 | } 234 | ``` 235 | 236 | 237 | ## Error Handling 238 | 239 | Utilize standard error handling practices as shown in the above example. 240 | 241 | Wrap any synchronous calls in a try/catch handler, and ensure to include the .catch() method on any async calls. 242 | 243 | ```javascript 244 | 245 | //Asynchronous error handling 246 | client 247 | .getIpGeolocationFull({ip:'8.8.8.8'}) 248 | .then((jsonResult=> { 249 | //success 250 | }) 251 | .catch(function(error) { 252 | console.error('Asynchronous "then" error:', error); 253 | }); 254 | 255 | //Synchronous error handling 256 | (async function() { 257 | try { 258 | //success 259 | } catch (error) { 260 | console.error('Asynchronous "await" error:', error); 261 | } 262 | })(); 263 | 264 | ``` 265 | -------------------------------------------------------------------------------- /demo.js: -------------------------------------------------------------------------------- 1 | const client = require('./index')('XXX'); // XXX being your api key found at: https://www.bigdatacloud.com/account 2 | 3 | /* 4 | * All api endpoints can be accessed via magic methods in the following camelised format: 5 | * method | endpoint 6 | * For example: an asynchronous "GET" call to the "ip-geolocation-full" endpoint would be: client.getIpGeolocationFull(); 7 | * All endpoints return a promise 8 | */ 9 | 10 | //Asynchronous example using 'then': 11 | client 12 | .getIpGeolocationFull({ip:'8.8.8.8'}) 13 | .then(jsonResult => { 14 | console.log('Asynchronous "then" result:',jsonResult); 15 | }).catch(exception => { 16 | console.log(exception); 17 | }); 18 | 19 | //Asynchronous example using 'await': 20 | (async () => { 21 | try { 22 | var jsonResult = await client.getIpGeolocationFull({ip:'8.8.8.8'}); 23 | console.log('Asynchronous "await" result:',jsonResult); 24 | } catch (error) { 25 | console.error('Asynchronous "await" error:', error); 26 | } 27 | })(); -------------------------------------------------------------------------------- /index.js: -------------------------------------------------------------------------------- 1 | const fetch = require('node-fetch'); 2 | 3 | class Client { 4 | constructor(apiKey, nameSpace, server) { 5 | var _this=this; 6 | this.apiKey=apiKey; 7 | this.nameSpace=nameSpace ? nameSpace : 'data'; 8 | this.server=server ? server : 'api.bigdatacloud.net'; 9 | 10 | return new Proxy(this,{ 11 | get:(t,p) => { 12 | if (typeof t[p]!=='undefined') return t[p]; 13 | return params => { 14 | var key=p; 15 | var method='GET'; 16 | 17 | key=key.replace(/([A-Z])/g,(m,c,o,i) => { 18 | return '-'+c.toLowerCase(); 19 | }); 20 | key=key.trim('-'); 21 | key=key.split('-'); 22 | 23 | if (key.length>1) { 24 | var methodTest=key[0].toUpperCase(); 25 | switch (methodTest) { 26 | case 'GET': 27 | case 'POST': 28 | case 'PUT': 29 | case 'DELETE': 30 | case 'OPTIONS': 31 | case 'PATCH': 32 | case 'HEAD': 33 | method=methodTest; 34 | key.shift(); 35 | break; 36 | } 37 | } 38 | var endpoint=key.join('-'); 39 | return _this.communicate(endpoint,method,params); 40 | } 41 | } 42 | }); 43 | } 44 | 45 | communicate(endpoint,method,payload) { 46 | var qs=[]; 47 | var data=false; 48 | var hasKey=false; 49 | if (!method) method='GET'; 50 | method=method.toUpperCase(); 51 | 52 | var url='https://'+this.server+'/'+this.nameSpace+'/'+endpoint; 53 | 54 | if (payload) { 55 | for (var i in payload) { 56 | if (i=='key') hasKey=true; 57 | qs.push(encodeURIComponent(i)+'='+encodeURIComponent(payload[i])); 58 | } 59 | } 60 | if (!hasKey) qs.push('key='+this.apiKey); 61 | 62 | if (qs.length && method=='GET' || method=='HEAD' || method=='DELETE') { 63 | if (qs.length) { 64 | url+=(url.indexOf('?')==-1 ? '?' : '&')+qs.join('&'); 65 | } 66 | } else if (qs.length) { 67 | data=qs.join('&'); 68 | } 69 | 70 | return this.talk(method,url,data); 71 | } 72 | 73 | talk(method,url,data) { 74 | return new Promise(async (resolve, reject) => { 75 | var payload={method:method}; 76 | if (method=='POST' || method=='PUT' || method=='PATCH') { 77 | payload.headers={'content-type' : 'application/x-www-form-urlencoded'}; 78 | } 79 | if (data) payload.body=data; 80 | try { 81 | const res=await fetch(url,payload); 82 | var json=await res.json(); 83 | if (!res.ok) { 84 | return reject({error:json,code:res.status}); 85 | } 86 | if (json) { 87 | return resolve(json); 88 | } 89 | return reject({error:res.body,code:res.status}); 90 | 91 | } catch (e) { 92 | reject({error:e,code:0}); 93 | } 94 | }); 95 | } 96 | }; 97 | 98 | module.exports=(apiKey,nameSpace,server) => { 99 | return new Client(apiKey,nameSpace,server); 100 | } -------------------------------------------------------------------------------- /package-lock.json: -------------------------------------------------------------------------------- 1 | { 2 | "name": "@bigdatacloudapi/client", 3 | "version": "1.1.4", 4 | "lockfileVersion": 2, 5 | "requires": true, 6 | "packages": { 7 | "": { 8 | "name": "@bigdatacloudapi/client", 9 | "version": "1.1.4", 10 | "license": "MIT", 11 | "dependencies": { 12 | "node-fetch": "^2.6.1" 13 | } 14 | }, 15 | "node_modules/node-fetch": { 16 | "version": "2.6.9", 17 | "resolved": "https://registry.npmjs.org/node-fetch/-/node-fetch-2.6.9.tgz", 18 | "integrity": "sha512-DJm/CJkZkRjKKj4Zi4BsKVZh3ValV5IR5s7LVZnW+6YMh0W1BfNA8XSs6DLMGYlId5F3KnA70uu2qepcR08Qqg==", 19 | "dependencies": { 20 | "whatwg-url": "^5.0.0" 21 | }, 22 | "engines": { 23 | "node": "4.x || >=6.0.0" 24 | }, 25 | "peerDependencies": { 26 | "encoding": "^0.1.0" 27 | }, 28 | "peerDependenciesMeta": { 29 | "encoding": { 30 | "optional": true 31 | } 32 | } 33 | }, 34 | "node_modules/tr46": { 35 | "version": "0.0.3", 36 | "resolved": "https://registry.npmjs.org/tr46/-/tr46-0.0.3.tgz", 37 | "integrity": "sha512-N3WMsuqV66lT30CrXNbEjx4GEwlow3v6rr4mCcv6prnfwhS01rkgyFdjPNBYd9br7LpXV1+Emh01fHnq2Gdgrw==" 38 | }, 39 | "node_modules/webidl-conversions": { 40 | "version": "3.0.1", 41 | "resolved": "https://registry.npmjs.org/webidl-conversions/-/webidl-conversions-3.0.1.tgz", 42 | "integrity": "sha512-2JAn3z8AR6rjK8Sm8orRC0h/bcl/DqL7tRPdGZ4I1CjdF+EaMLmYxBHyXuKL849eucPFhvBoxMsflfOb8kxaeQ==" 43 | }, 44 | "node_modules/whatwg-url": { 45 | "version": "5.0.0", 46 | "resolved": "https://registry.npmjs.org/whatwg-url/-/whatwg-url-5.0.0.tgz", 47 | "integrity": "sha512-saE57nupxk6v3HY35+jzBwYa0rKSy0XR8JSxZPwgLr7ys0IBzhGviA1/TUGJLmSVqs8pb9AnvICXEuOHLprYTw==", 48 | "dependencies": { 49 | "tr46": "~0.0.3", 50 | "webidl-conversions": "^3.0.0" 51 | } 52 | } 53 | }, 54 | "dependencies": { 55 | "node-fetch": { 56 | "version": "2.6.9", 57 | "resolved": "https://registry.npmjs.org/node-fetch/-/node-fetch-2.6.9.tgz", 58 | "integrity": "sha512-DJm/CJkZkRjKKj4Zi4BsKVZh3ValV5IR5s7LVZnW+6YMh0W1BfNA8XSs6DLMGYlId5F3KnA70uu2qepcR08Qqg==", 59 | "requires": { 60 | "whatwg-url": "^5.0.0" 61 | } 62 | }, 63 | "tr46": { 64 | "version": "0.0.3", 65 | "resolved": "https://registry.npmjs.org/tr46/-/tr46-0.0.3.tgz", 66 | "integrity": "sha512-N3WMsuqV66lT30CrXNbEjx4GEwlow3v6rr4mCcv6prnfwhS01rkgyFdjPNBYd9br7LpXV1+Emh01fHnq2Gdgrw==" 67 | }, 68 | "webidl-conversions": { 69 | "version": "3.0.1", 70 | "resolved": "https://registry.npmjs.org/webidl-conversions/-/webidl-conversions-3.0.1.tgz", 71 | "integrity": "sha512-2JAn3z8AR6rjK8Sm8orRC0h/bcl/DqL7tRPdGZ4I1CjdF+EaMLmYxBHyXuKL849eucPFhvBoxMsflfOb8kxaeQ==" 72 | }, 73 | "whatwg-url": { 74 | "version": "5.0.0", 75 | "resolved": "https://registry.npmjs.org/whatwg-url/-/whatwg-url-5.0.0.tgz", 76 | "integrity": "sha512-saE57nupxk6v3HY35+jzBwYa0rKSy0XR8JSxZPwgLr7ys0IBzhGviA1/TUGJLmSVqs8pb9AnvICXEuOHLprYTw==", 77 | "requires": { 78 | "tr46": "~0.0.3", 79 | "webidl-conversions": "^3.0.0" 80 | } 81 | } 82 | } 83 | } 84 | -------------------------------------------------------------------------------- /package.json: -------------------------------------------------------------------------------- 1 | { 2 | "name": "@bigdatacloudapi/client", 3 | "version": "1.1.4", 4 | "description": "A NodeJS client for BigDataCloud API connectivity (https://www.bigdatacloud.com)", 5 | "main": "index.js", 6 | "repository": { 7 | "type": "git", 8 | "url": "git+https://github.com/bigdatacloudapi/nodejs-api-client.git" 9 | }, 10 | "keywords": [ 11 | "ip-geolocation", 12 | "bigdatacloud", 13 | "bigdatacloudapi" 14 | ], 15 | "author": "BigDataCloud", 16 | "license": "MIT", 17 | "bugs": { 18 | "url": "https://github.com/bigdatacloudapi/nodejs-api-client/issues" 19 | }, 20 | "homepage": "https://github.com/bigdatacloudapi/nodejs-api-client#readme", 21 | "dependencies": { 22 | "node-fetch": "^2.6.1" 23 | }, 24 | "engines": { 25 | "node": ">=14.0.0" 26 | }, 27 | "scripts": { 28 | "test": "echo \"No test specified\"" 29 | } 30 | } 31 | --------------------------------------------------------------------------------