AIS Hub Getting Started: Account, Keys, and First API Call (2026)

Getting started overview

Getting started with the AIS Hub API involves a sequence of steps designed to enable access to real-time and historical Automatic Identification System (AIS) data for maritime vessels. This process typically begins with account creation, followed by the generation and secure management of an API key. This key is used to authenticate requests to the AIS Hub API, which provides endpoints for querying vessel positions, movements, and related information. The service offers a free tier that allows for initial development and testing with a limit of 5,000 requests per month, providing a mechanism to evaluate the API's capabilities before migrating to paid plans. Developers can integrate the API into applications for purposes such as maritime vessel tracking, port operations monitoring, logistics, and marine traffic analysis by utilizing standard HTTP requests and processing JSON responses, as outlined in the official AIS Hub API documentation.

The workflow for integration is structured to guide users from initial setup to making a functional API call. This includes understanding the required parameters for different API endpoints and handling potential errors. AIS Hub provides specific examples in languages such as PHP, Python, JavaScript, Ruby, Java, and C#, facilitating the process for developers familiar with these environments. The API documentation serves as the primary resource for detailed endpoint descriptions, request formats, and response structures, ensuring that developers have the necessary information for successful implementation and ongoing maintenance.

Create an account and get keys

To begin using the AIS Hub API, account creation is the initial step. This process establishes a user profile and grants access to the dashboard where API keys are managed. Accessing the AIS Hub homepage allows users to navigate to the registration portal.

1. Register for an account: Visit the AIS Hub website and locate the 'Sign Up' or 'Register' option. Provide the required information, such as email address and password, to create a new user account. An email verification step typically follows to confirm the account.
2. Log in to the dashboard: After successful registration and email verification, log in to the AIS Hub user dashboard using the newly created credentials.
3. Generate an API key: Within the dashboard, there is a section dedicated to API key management. This section typically allows users to generate new keys, view existing keys, and manage their status. Click the option to generate a new API key. The generated key is a unique alphanumeric string that acts as the authentication token for all API requests.
4. Securely store your API key: The API key provides access to your AIS Hub account's allocated requests and data. It should be treated as sensitive information. Best practices for securing API keys include storing them as environment variables, using a secrets management service, or passing them securely in application configurations rather than hardcoding them directly into source code. For local development, an .env file is a common method, ensuring the file is excluded from version control systems via a .gitignore entry.

The AIS Hub API utilizes the API key as a query parameter in each request. For example, a request might include ?apikey=YOUR_API_KEY. This method is a common approach for authenticating API access for services that do not require OAuth 2.0 or other more complex authentication flows, as detailed in general API security guidelines for using API keys securely.

Your first request

Once an API key has been generated and securely stored, the next step is to make a first API call to retrieve data. This involves constructing a URL with the appropriate endpoint, parameters, and the API key. The AIS Hub API provides various endpoints for different types of maritime data. A common starting point is to fetch real-time vessel data or information about a specific vessel.

Real-time vessel data example

To retrieve a list of vessels within a specified area, you might use an endpoint like /v1/getjson.php with parameters for latitude, longitude, and radius, along with your API key. The AIS Hub API documentation provides specific examples for this type of query.

GET https://data.aishub.net/ws/v1/getjson.php?apikey=YOUR_API_KEY&lat=34.0522&lon=-118.2437&radius=50&output=json

Replace YOUR_API_KEY with the key obtained from your dashboard. The lat and lon parameters represent the central coordinates (e.g., Los Angeles, USA), and radius specifies the search area in kilometers. The output=json parameter ensures the response is in JSON format.

Using Python to make the request

This Python example demonstrates how to make a GET request to the AIS Hub API and print the JSON response.

import requests
import json

API_KEY = "YOUR_API_KEY" # Replace with your actual API key
BASE_URL = "https://data.aishub.net/ws/v1/getjson.php"

params = {
    "apikey": API_KEY,
    "lat": 34.0522,      # Latitude for Los Angeles
    "lon": -118.2437,    # Longitude for Los Angeles
    "radius": 50,        # Radius in kilometers
    "output": "json"
}

try:
    response = requests.get(BASE_URL, params=params)
    response.raise_for_status()  # Raise an exception for HTTP errors (4xx or 5xx)

    data = response.json()
    print(json.dumps(data, indent=2))

except requests.exceptions.HTTPError as err:
    print(f"HTTP error occurred: {err}")
except requests.exceptions.ConnectionError as err:
    print(f"Connection error occurred: {err}")
except requests.exceptions.Timeout as err:
    print(f"Timeout error occurred: {err}")
except requests.exceptions.RequestException as err:
    print(f"An unexpected error occurred: {err}")

After executing this script, the console should display a JSON array containing information about vessels detected within the specified geographical radius. This confirms successful communication with the AIS Hub API and proper authentication using the API key.

Quick Reference: Getting Started Steps

Common next steps

After making a successful initial API call, developers typically proceed with further integration and refinement of their application. These common next steps focus on expanding functionality, optimizing data usage, and ensuring the application scales effectively.

1. Explore additional API endpoints: The AIS Hub API documentation details various endpoints beyond real-time vessel tracking. These may include historical data access, specific vessel details by MMSI (Maritime Mobile Service Identity), or port-related information. Understanding the full range of available data allows for more comprehensive application development.
2. Implement error handling and retry logic: Robust applications anticipate and manage potential API errors, such as rate limits (HTTP 429), invalid API keys (HTTP 401), or server-side issues (HTTP 5xx). Implementing proper error handling ensures that the application degrades gracefully or retries requests when appropriate, as suggested by general practices for implementing exponential backoff for API requests.
3. Optimize data retrieval: For applications requiring frequent updates or large volumes of data, optimizing API calls is crucial. This might involve using specific parameters to filter data at the source, caching frequently accessed static data, or implementing webhooks if AIS Hub supports push notifications for updates (check API documentation for webhook availability).
4. Monitor API usage: Keep track of your API request volume against your rate limits, especially when operating on the free tier or a specific paid plan. The AIS Hub dashboard usually provides metrics on API usage, helping to prevent unexpected service interruptions due to exceeding quotas.
5. Consider scaling and performance: As your application grows, evaluate its performance and consider strategies for scaling. This might involve optimizing database interactions, distributing loads, or upgrading to a higher-tier AIS Hub plan to accommodate increased request volumes and data throughput.
6. Integrate with other services: Maritime data often complements other datasets. Consider integrating AIS Hub data with mapping services (e.g., ArcGIS mapping tools or Google Maps Platform), weather APIs, or logistics platforms to provide richer insights and features within your application.
7. Set up development and production environments: Differentiate between development and production API keys and configurations. This ensures that testing and experimentation do not impact live production environments and that production keys are handled with stricter security protocols.

Troubleshooting the first call

Encountering issues during the first API call is common. Here are troubleshooting steps for frequent problems:

• Invalid API Key (HTTP 401):
  • Verification: Double-check that the API key in your request exactly matches the key generated in your AIS Hub dashboard. Ensure no extra spaces or characters are included.
  • Placement: Confirm the API key is passed correctly as a query parameter (e.g., ?apikey=YOUR_KEY) as specified in the AIS Hub documentation.
  • Activation: Some API keys require activation after generation. Check your dashboard for any pending activation steps.
• Rate Limit Exceeded (HTTP 429):
  • Usage Check: If you are on the free tier (5,000 requests/month) or a specific paid plan, you might have exceeded your allocated request limit. Check your AIS Hub dashboard for current usage statistics.
  • Wait Period: Implement a delay before retrying the request. For sustained usage, consider upgrading your plan.
• Bad Request (HTTP 400):
  • Parameter Check: Review all parameters (e.g., lat, lon, radius) for correct data types, formats, and valid ranges as per the API documentation. Incorrect or missing mandatory parameters often lead to this error.
  • Endpoint Accuracy: Verify that the endpoint URL is correct (e.g., /v1/getjson.php) and matches the desired API function.
• Server Error (HTTP 5xx):
  • Retry: These are typically temporary server-side issues. Implement retry logic with exponential backoff.
  • Status Page: Check the AIS Hub website or any provided status pages for known service outages.
• Connection Issues:
  • Network: Ensure your internet connection is stable.
  • Firewall/Proxy: If you are within a corporate network, firewalls or proxy servers might be blocking outbound API calls. Consult your network administrator.
  • DNS Resolution: Verify that data.aishub.net resolves correctly using tools like ping or nslookup.
• Empty or Unexpected Response:
  • Geographical Area: If you are querying for vessels in a specific area, ensure the lat, lon, and radius parameters cover an area where vessels are likely to be present. Test with coordinates of major shipping lanes or ports initially.
  • Filters: Check if any implicit or explicit filters in your request are too restrictive, leading to no results.
  • Data Format: Ensure you are requesting the correct output format (e.g., output=json) and parsing it correctly in your code.