VisitorAPI

https://www.visitorapi.com/docs
Admin
VisitorAPI is a REST API and SDK that detects website visitors' IP address, location, currency,...
Tokens:3,673
Snippets:42
Trust Score:6.3
Update:1 month ago
Show doc for...
Tokens:
Raw
### Install VisitorAPI SDK

Source: https://www.visitorapi.com/docs/javascript-sdk

Install the package via npm to begin using the SDK in your project.

```bash
npm install visitorapi
```

--------------------------------

### Full Visitor API Implementation

Source: https://www.visitorapi.com/docs/get-started

A complete example showing the client definition followed by an API call with success and error handlers.

```javascript
var VisitorAPI=function(t,e,a){var s=new XMLHttpRequest;s.onreadystatechange=function(){var t;s.readyState===XMLHttpRequest.DONE&&(200===(t=JSON.parse(s.responseText)).status?e(t.data):a(t.status,t.result))},s.open("GET","https://api.visitorapi.com/api/?pid="+t),s.send(null)};

VisitorAPI(
    "om61tWZOjuBBPxTdDlpy",
    function(data){console.log(data)},
    function(errorCode, errorMessage){console.log(errorCode, errorMessage)}
);
```

--------------------------------

### Visitor API JSON Response Structure

Source: https://www.visitorapi.com/docs/visitor-data

Example of the JSON object returned to the success handler function.

```json
{
	"ipAddress":"118.211.184.103",
	"countryCode":"AU",
	"countryName":"Australia",
	"currencies":["AUD"],
	"languages":["eng"],
	"region":"nsw",
	"city":"sydney",
	"cityLatLong":"-33.868820,151.209295",
	"browser":"Chrome Mobile iOS",
	"browserVersion":"100",
	"deviceBrand":"Apple",
	"deviceModel":"iPad",
	"deviceFamily":"iPad",
	"os":"iOS",
	"osVersion":"15"
}
```

--------------------------------

### API Error Handling Reference

Source: https://www.visitorapi.com/docs/error-handling

A reference guide for interpreting error codes and messages returned by the API.

```APIDOC
## Error Handling

### Description
When an error occurs, the API returns an error code and message. The HTTP header is also set to the corresponding error code.

### Error Codes
| Error Code | Error Message | Description |
|---|---|---|
| 400 | "Error: missing project ID parameter pid" | The request is missing the required 'pid' parameter. |
| 404 | "Error: cannot find the project" | No project matches the provided 'pid'. |
| 403 | "Error: no domain is allowed" | The domain is not in the authorized domain list. |
| 403 | "Error: referrer domain is not allowed" | The domain is not authorized or a no-referrer policy is active. |
| 402 | "Error: exceed free plan quota, please upgrade" | Monthly usage quota exceeded. |
| 500 | "Internal error" | Unexpected internal server error. |
```

--------------------------------

### Populate React State with VisitorAPI Data

Source: https://www.visitorapi.com/docs/react/sdk

Example showing how to map returned visitor data to individual React state variables within a useEffect hook.

```javascript
const VisitorAPI = require("visitorapi");

const [visitorData, setVisitorData] = useState({}); // store the whole json
const [ipAddress, setIpAddress] = useState("");
const [countryCode, setCountryCode] = useState("");
const [countryName, setCountryName] = useState("");
const [state, setState] = useState("");
const [city, setCity] = useState("");
const [cityLatLong, setCityLatLong] = useState(""); // city center latitude and longitude
const [currencies, setCurrencies] = useState([]); // currencies data is an array
const [languages, setLanguages] = useState([]); // languages data is an array
const [browser, setBrowser] = useState("");
const [browserVersion, setBrowserVersion] = useState("");
const [deviceBrand, setDeviceBrand] = useState("");
const [deviceModel, setDeviceModel] = useState("");
const [deviceFamily, setDeviceFamily] = useState("");
const [os, setOs] = useState("");
const [osVersion, setOsVersion] = useState("");

useEffect(() => {
   VisitorAPI("project id").then(data => {
      setVisitorData(data);
      setIpAddress(data.ipAddress);
      setCountryCode(data.countryCode);
      setCountryName(data.countryName);
      setState(data.region);
      setCity(data.city);
      setCityLatLong(data.cityLatLong);
      setCurrencies(data.currencies);
      setLanguages(data.languages);
      setBrowser(data.browser);
      setBrowserVersion(data.browserVersion);
      setDeviceBrand(data.deviceBrand);
      setDeviceModel(data.deviceModel);
      setDeviceFamily(data.deviceFamily);
      setOs(data.os);
      setOsVersion(data.osVersion);
   }).catch(error => {
      // handle error
   });
},[]);
```

--------------------------------

### Initialize SDK with Callback API

Source: https://www.visitorapi.com/docs/javascript-sdk

Use the callback-based approach to handle visitor data retrieval with success and error handlers.

```javascript
const VisitorAPI = require("visitorapi");

VisitorAPI(
  "your-project-id",
  data => {
    console.log(data.countryCode);
  },
  error => {
    // handle error
  }
);
```

--------------------------------

### Initialize SDK with Promise API

Source: https://www.visitorapi.com/docs/javascript-sdk

Use the Promise-based approach to handle visitor data retrieval asynchronously.

```javascript
const VisitorAPI = require("visitorapi");

VisitorAPI("your-project-id")
  .then(data => {
    console.log(data.countryCode);
  })
  .catch(error => {
    // handle error
  });
```

--------------------------------

### new VisitorAPI(projectID, successHandler, errorHandler)

Source: https://www.visitorapi.com/docs/get-started

Initializes and calls the Visitor API to retrieve visitor data.

```APIDOC
## new VisitorAPI(projectID, successHandler, errorHandler)

### Description
Initializes the Visitor API client and executes a request to fetch visitor information based on the provided project ID.

### Parameters
- **projectID** (string) - Required - Unique identifier of the project created in the VisitorAPI interface.
- **successHandler** (function) - Required - Callback function to process visitor data on a successful API call. Receives the data object as an argument.
- **errorHandler** (function) - Required - Callback function to handle errors. Receives the errorCode and errorMessage as arguments.

### Example
```javascript
VisitorAPI(
    "om61tWZOjuBBPxTdDlpy",
    function(data){console.log(data)},
    function(errorCode, errorMessage){console.log(errorCode, errorMessage)}
);
```
```

--------------------------------

### VisitorAPI(projectId, successCallback, errorCallback)

Source: https://www.visitorapi.com/docs/javascript-sdk

Initializes the VisitorAPI client using a callback-based approach to fetch visitor data.

```APIDOC
## VisitorAPI(projectId, successCallback, errorCallback)

### Description
Fetches visitor data using callback functions for success and error handling.

### Parameters
- **projectId** (string) - Required - The unique identifier for your project.
- **successCallback** (function) - Required - Function called with the visitor data object upon success.
- **errorCallback** (function) - Required - Function called with an error object upon failure.

### Usage Example
```javascript
const VisitorAPI = require("visitorapi");

VisitorAPI(
  "your-project-id",
  data => {
    console.log(data.countryCode);
  },
  error => {
    // handle error
  }
);
```
```

--------------------------------

### VisitorAPI(projectId)

Source: https://www.visitorapi.com/docs/react/sdk

The primary function to initialize the SDK and retrieve visitor data. It returns a promise that resolves with the visitor's information.

```APIDOC
## VisitorAPI(projectId)

### Description
Calls the VisitorAPI service to retrieve visitor data such as location, browser, OS, and device information.

### Parameters
- **projectId** (string) - Required - The unique identifier for your project in VisitorAPI.

### Returns
- **Promise** - Resolves with a JSON object containing visitor data (ipAddress, countryCode, countryName, region, city, cityLatLong, currencies, languages, browser, browserVersion, deviceBrand, deviceModel, deviceFamily, os, osVersion).

### Example
```javascript
const VisitorAPI = require("visitorapi");

VisitorAPI("your-project-id").then(data => {
    console.log(data);
}).catch(error => {
    console.error(error);
});
```
```

--------------------------------

### VisitorAPI(projectId)

Source: https://www.visitorapi.com/docs/javascript-sdk

Initializes the VisitorAPI client using a Promise-based approach to fetch visitor data.

```APIDOC
## VisitorAPI(projectId)

### Description
Fetches visitor data using a Promise-based interface. Returns a promise that resolves with the visitor data object.

### Parameters
- **projectId** (string) - Required - The unique identifier for your project from the VisitorAPI dashboard.

### Usage Example
```javascript
const VisitorAPI = require("visitorapi");

VisitorAPI("your-project-id")
  .then(data => {
    console.log(data.countryCode);
  })
  .catch(error => {
    // handle error
  });
```
```

--------------------------------

### Initialize Visitor API Client

Source: https://www.visitorapi.com/docs/get-started

Include this function definition in your web pages to enable communication with the Visitor API.

```javascript
var VisitorAPI=function(t,e,a){var s=new XMLHttpRequest;s.onreadystatechange=function(){var t;s.readyState===XMLHttpRequest.DONE&&(200===(t=JSON.parse(s.responseText)).status?e(t.data):a(t.status,t.result))},s.open("GET","https://api.visitorapi.com/api/?pid="+t),s.send(null)};
```

--------------------------------

### Call Visitor API Syntax

Source: https://www.visitorapi.com/docs/get-started

Use this syntax to invoke the API after the client function has been defined.

```javascript
new VisitorAPI(projectID, successHandler, errorHandler);
```

--------------------------------

### Call VisitorAPI in React

Source: https://www.visitorapi.com/docs/react/sdk

Basic implementation for fetching visitor data using a project ID.

```javascript
const VisitorAPI = require("visitorapi");

VisitorAPI("project id").then(data => {
    // handle the return data in json
}).catch(error => {
    // handle error
});
```

--------------------------------

### Visitor Data Response Format

Source: https://www.visitorapi.com/docs/visitor-data

The API returns a JSON object to the success handler function containing detailed visitor information.

```APIDOC
## Visitor Data Response

### Description
The Visitor API returns a JSON object to the success handler function. This data can be used to personalize web pages based on the visitor's location, device, and browser.

### Response Fields
- **ipAddress** (string) - The IP address of the visitor.
- **countryCode** (string) - ISO 3166-1 alpha-2 country code.
- **countryName** (string) - Full name of the country.
- **currencies** (array) - Official currencies of the country.
- **languages** (array) - Official languages of the country.
- **region** (string) - Name of the region, state, or province (ISO-3166-2).
- **city** (string) - Name of the city.
- **cityLatLong** (string) - Latitude and longitude of the city.
- **browser** (string) - Browser name.
- **browserVersion** (string) - Browser version.
- **deviceBrand** (string) - Device brand (mobile only).
- **deviceModel** (string) - Device model (mobile only).
- **deviceFamily** (string) - Device family (mobile only).
- **os** (string) - Operating system name.
- **osVersion** (string) - Operating system version.

### Response Example
{
	"ipAddress": "118.211.184.103",
	"countryCode": "AU",
	"countryName": "Australia",
	"currencies": ["AUD"],
	"languages": ["eng"],
	"region": "nsw",
	"city": "sydney",
	"cityLatLong": "-33.868820,151.209295",
	"browser": "Chrome Mobile iOS",
	"browserVersion": "100",
	"deviceBrand": "Apple",
	"deviceModel": "iPad",
	"deviceFamily": "iPad",
	"os": "iOS",
	"osVersion": "15"
}
```
Tokens:
Raw