API Documentation

Introduction

The HumansMapped API provides access to a vast array of datasets covering various topics, including demographics, economics, health, and more. By integrating our API, you can enhance your applications with valuable data insights.

This API allows developers to access a rich collection of datasets hosted on our platform. You can:

  • List all available datasets

  • Retrieve specific datasets, with optional filtering by years

Authentication

To use the HumansMapped API, you need to authenticate each request using your username and API key.

Obtaining an API Key

  1. Sign Up: Create an account on app.HumansMapped.com

  2. Generate API Key:

    • Log in to your account.

    • Navigate in the app to Menu.

    • Click on Generate API Key.

  3. Secure Your API Key:

    • Treat your API key like a password.

    • Do not share your API key publicly.

    • Store it securely in your application.

API Endpoint

All API requests are made to the following endpoint:

https://api.humansmapped.com/humansmapped_api/dataset

Request Structure

  • HTTP Method: POST

  • Content-Type: application/json

  • Authentication: Include username and api_key in the JSON payload.

Usage

1. Listing All Datasets

To retrieve a list of all available datasets, send a POST request without the dataset_name parameter.

Request Payload

curl -X POST \
     -H "Content-Type: application/json" \
     -d '{
           "username": "your_email@example.com",
           "api_key": "your_api_key_here"
         }' \
     https://api.humansmapped.com/humansmapped_api/dataset

{
  "username": "your_email@example.com",
  "api_key": "your_api_key_here"
}

Example cURL Request

{
  "datasets": [
    "population_by_country.csv",
    "gdp_growth.csv",
    "climate_change_impacts.csv",
    "... more datasets ..."
  ]
}

Response

2. Retrieving a Specific Dataset

To retrieve a specific dataset, include the dataset_name in your request. You can optionally filter the data by specifying the years parameter.

Request Payload

{
  "username": "your_email@example.com",
  "api_key": "your_api_key_here",
  "dataset_name": "population_by_country.csv",
  "years": [2010, 2015, 2020]
}

curl -X POST \
     -H "Content-Type: application/json" \
     -d '{
           "username": "your_email@example.com",
           "api_key": "your_api_key_here",
           "dataset_name": "population_by_country.csv",
           "years": [2010, 2015, 2020]
         }' \
     https://api.humansmapped.com/humansmapped_api/dataset

dataset_name: (Required) The name of the dataset you want to retrieve.

  • years: (Optional) A list of years to filter the data.

Example cURL Request

Response

{
  "dataset": "population_by_country.csv",
  "data": [
    {
      "Entity": "United States",
      "2010": 309.35,
      "2015": 320.74,
      "2020": 331.00
    },
    {
      "Entity": "China",
      "2010": 1340.91,
      "2015": 1376.05,
      "2020": 1439.32
    },
    {
      "Entity": "India",
      "2010": 1230.98,
      "2015": 1311.05,
      "2020": 1380.00
    },
    "... more records ..."
  ]
}

Examples

Python Example

Below is a Python example using the requests and pandas libraries to interact with the API.

Requirements

  • Python 3.x

  • Libraries:

    • requests

    • pandas

Installation

pip install requests pandas
import requests
import pandas as pd

# API endpoint
DATASET_URL = "https://api.humansmapped.com/humansmapped_api/dataset"

# Your credentials
USERNAME = "your_email@example.com"
API_KEY = "your_api_key_here"

# Function to list all datasets
def list_datasets():
    payload = {
        "username": USERNAME,
        "api_key": API_KEY
    }
    response = requests.post(DATASET_URL, json=payload)
    response.raise_for_status()
    datasets = response.json().get("datasets", [])
    print("Available Datasets:")
    for dataset in datasets:
        print(f"- {dataset}")
    return datasets

# Function to retrieve a specific dataset
def retrieve_dataset(dataset_name, years=None):
    payload = {
        "username": USERNAME,
        "api_key": API_KEY,
        "dataset_name": dataset_name
    }
    if years:
        payload["years"] = years
    response = requests.post(DATASET_URL, json=payload)
    response.raise_for_status()
    data = response.json()
    if 'error' in data:
        print(f"Error: {data['error']}")
        return None
    df = pd.DataFrame(data['data'])
    print(f"\nDataset: {data['dataset']}")
    print(df.head())
    return df

# Example usage
if __name__ == "__main__":
    # List datasets
    datasets = list_datasets()
    if datasets:
        # Retrieve a specific dataset
        dataset_name = datasets[0]  # For example purposes
        retrieve_dataset(dataset_name, years=[2010, 2015, 2020])

Code Example

Sample Output

Available Datasets:
- population_by_country.csv
- gdp_growth.csv
- climate_change_impacts.csv
- ... more datasets ...

Dataset: population_by_country.csv
           Entity     2010     2015     2020
0  United States   309.35   320.74   331.00
1          China  1340.91  1376.05  1439.32
2          India  1230.98  1311.05  1380.00
3         Brazil   195.21   204.47   212.56
4         Russia   142.85   146.27   145.93

Error Handling

The API returns errors in a consistent JSON format:

{
  "error": "Error message describing the issue."
}

Common Errors

  • Authentication Errors:

    • HTTP Status Code: 400 Bad Request or 403 Forbidden

    • Messages:

      • "Username and API key are required."

      • "Invalid API key."

  • Rate Limiting:

    • HTTP Status Code: 429 Too Many Requests

    • Message: "Rate limit exceeded. Try again later."

  • Dataset Not Found:

    • HTTP Status Code: 404 Not Found

    • Message: "Dataset 'dataset_name.csv' not found."

  • Invalid Parameters:

    • HTTP Status Code: 400 Bad Request

    • Message: "No matching years found in the dataset."

Handling Errors in Code

response = requests.post(DATASET_URL, json=payload)
try:
    response.raise_for_status()
    data = response.json()
    if 'error' in data:
        print(f"Error: {data['error']}")
except requests.exceptions.HTTPError as http_err:
    print(f"HTTP error occurred: {http_err}")
except Exception as err:
    print(f"Other error occurred: {err}")

Rate Limiting

To ensure fair usage, the API enforces rate limiting:

  • Limit: 10 requests per minute per user.

  • Exceeded Limit:

    • HTTP Status Code: 429 Too Many Requests

    • Message: "Rate limit exceeded. Try again later."

Best Practices

  • Implement Backoff: If you receive a 429 error, wait before retrying.

  • Efficient Requests: Fetch only the data you need.

  • Caching: Cache responses when appropriate to reduce API calls.

Support and Contact Information

Need assistance? We're here to help!

The HumansMapped API empowers you to integrate comprehensive datasets into your applications seamlessly. With straightforward authentication and clear endpoints, you can quickly start leveraging our data for your analytical and development needs.

Happy coding! 🚀



© 2023 HumansMapped. All rights reserved.