Nationalize.io Getting Started: Quickstart Guide (2026)

Getting started overview

This guide outlines the steps required to begin using the Nationalize.io API, focusing on account creation, API key retrieval, and making an initial request. Nationalize.io allows developers to predict the most likely nationality of a person based on their first name. The API accepts a name as a query parameter and returns a JSON object containing a list of countries with associated probabilities. This can be used for various applications, including demographic analysis, marketing segmentation, and personalization efforts.

The core interaction with the Nationalize.io API involves sending an HTTP GET request to a specific endpoint. Authentication is handled via an API key, which is obtained after registering for an account. The API is designed for straightforward integration, providing clear documentation and code examples across several programming languages to facilitate development.

For a complete overview of all available endpoints, parameters, and response structures, refer to the Nationalize.io API documentation.

Quick reference table

Create an account and get keys

To access the Nationalize.io API, you must first create an account and obtain an API key. This key authenticates your requests and tracks your usage against your subscription plan.

Account registration

1. Visit the Nationalize.io website: Navigate to the Nationalize.io homepage.
2. Choose a plan: Click on the 'Pricing' or 'Sign Up' link, which will direct you to the Nationalize.io pricing page. Nationalize.io offers a free tier that includes 1,000 requests per month, which is sufficient for initial testing and development. Select the 'Free' plan or a paid tier that suits your needs.
3. Complete registration: Provide the required information, typically an email address and password, to create your account. Some services may require email verification.
4. Log in: Once registered, log in to your Nationalize.io dashboard.

API key retrieval

Upon successful login to your dashboard, your API key should be prominently displayed. It is a unique string of characters that identifies your account for every API request you make. Treat your API key like a password; keep it secure and do not expose it in client-side code or public repositories. If your API key is compromised, most services offer a mechanism to regenerate it from your account dashboard.

Your first request

After obtaining your API key, you can make your first API call. The primary endpoint for nationality prediction is https://api.nationalize.io/. You will need to pass the name you want to analyze as a query parameter.

Request structure

The basic request structure involves:

• Base URL: https://api.nationalize.io/
• Query Parameter: name (the name to predict nationality for)
• API Key: Passed as a query parameter, typically named apikey or similar, though Nationalize.io's documentation implies it's often handled implicitly after account setup or via a dashboard setting for free tier users. For robust API security, an API key is usually included as a query parameter or in the Authorization header, as detailed in general Cloudflare API request security guidelines. Refer to the Nationalize.io API documentation for exact API key usage.

Example request (cURL)

Using cURL is a common way to test RESTful APIs directly from the command line. Replace YOUR_API_KEY with your actual API key and john with the name you wish to query.

curl "https://api.nationalize.io/?name=john&apikey=YOUR_API_KEY"

Note: While the above example includes apikey, Nationalize.io's free tier often doesn't require an explicit API key in the URL for basic requests, relying on your account's IP address or other session data after logging in. Always check the official Nationalize.io API documentation for the most up-to-date and accurate method of including your API key.

Example response

A successful request will return a JSON object similar to this:

{
  "name": "john",
  "country": [
    {
      "country_id": "US",
      "probability": 0.081
    },
    {
      "country_id": "GB",
      "probability": 0.075
    },
    {
      "country_id": "AU",
      "probability": 0.063
    }
  ]
}

The response includes the queried name and an array of country objects. Each country object contains a country_id (an ISO 3166-1 alpha-2 code) and a probability score, indicating the likelihood of that nationality. The probabilities sum to 1 for the top predicted countries.

Common next steps

Once you have successfully made your first API call, consider these next steps for further integration and development:

1. Explore multiple names: The API supports querying multiple names in a single request by repeating the name query parameter (e.g., ?name=john&name=jane). Experiment with this feature to optimize your API calls.
2. Integrate into an application: Begin incorporating the API calls into your chosen programming language. Nationalize.io provides documentation with code examples in languages like Python, PHP, Ruby, Node.js, Go, and Java.
3. Handle rate limits: Understand the rate limits associated with your chosen plan (e.g., 1,000 requests/month for the free tier). Implement a strategy to manage your request volume and handle potential 429 Too Many Requests responses.
4. Error handling: Implement robust error handling in your application to gracefully manage API errors, such as invalid inputs or server issues.
5. Monitor usage: Regularly check your Nationalize.io dashboard to monitor your API usage and ensure you stay within your plan's limits.
6. Consider batch processing: For large datasets, evaluate the efficiency of making multiple individual requests versus any potential batch processing capabilities offered by the API, if available.
7. Review pricing plans: If your usage exceeds the free tier, review the Nationalize.io pricing page to select a paid plan that aligns with your anticipated request volume.

Troubleshooting the first call

If your first API call does not return the expected result, consider the following common issues:

• Invalid API Key: Double-check that you have copied your API key correctly from your Nationalize.io dashboard. Even a single incorrect character can lead to authentication failures.
• Missing API Key: Ensure your API key is included in the request according to the Nationalize.io API documentation. While some free tiers might not strictly enforce it in the URL, authenticated requests typically require it.
• Incorrect Endpoint: Verify that you are sending the request to the correct base URL (https://api.nationalize.io/) and that the endpoint path is accurate.
• Missing or Incorrect Parameters: Ensure the name query parameter is correctly spelled and has a value. For example, ?name=john is correct, while ?Name=john (incorrect capitalization) or ?name= (missing value) might cause issues.
• Network Issues: Check your internet connection. If you are behind a firewall or proxy, ensure it is not blocking outgoing requests to api.nationalize.io.
• Rate Limiting: If you are making many requests in a short period, you might hit a rate limit, especially on the free tier. Wait a few moments and try again, or check your dashboard for usage statistics.
• JSON Parsing Errors: If you receive a response but cannot parse it, ensure your code correctly handles JSON. Malformed JSON responses are rare but can indicate a server-side issue or an unexpected error format.
• Refer to Documentation: The Nationalize.io API documentation often contains a dedicated section for common errors and their resolutions. Review it for specific error codes you might be encountering.