🚀 Getting Started

Overview

YouMap Public API allows you to integrate with our mapping platform to create, manage, and interact with location-based content.

Quick Start

Sign up for an account at YouMap
Generate clientId and clientSecret in the API Key Generator tab
Get your JWT token using the login endpoint
Start making authenticated requests to our API

Step 3: Getting Your JWT Token

Once you have your clientId and clientSecret, use them to authenticate and get a JWT token:

Login Endpoint

POST /api/v1/auth

Request Body

{
  "clientId": "your_client_id_here",
  "clientSecret": "your_client_secret_here"
}

Example Request

curl -X POST "https://developer.youmap.com/api/v1/auth" \
  -H "Content-Type: application/json" \
  -d '{
    "clientId": "your_client_id_here",
    "clientSecret": "your_client_secret_here"
  }'

Response

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expiresIn": 3600
}

JavaScript Example

const response = await fetch('https://developer.youmap.com/api/v1/auth', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    clientId: 'your_client_id_here',
    clientSecret: 'your_client_secret_here'
  })
});

const data = await response.json();
const jwtToken = data.token;

// Now use the JWT token for authenticated requests
const mapsResponse = await fetch('https://developer.youmap.com/api/v1/maps', {
  headers: {
    'Authorization': `Bearer ${jwtToken}`,
    'Content-Type': 'application/json'
  }
});

Base URL

https://developer.youmap.com/api/v1

Making Authenticated Requests

After obtaining your JWT token, include it in the Authorization header for all API requests:

curl -X GET "https://developer.youmap.com/api/v1/maps" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json"

Token Expiration

JWT tokens expire after a certain period (shown in the expiresIn field). When your token expires, you'll need to request a new one using the same login endpoint with your clientId and clientSecret.

For Developers & AI Tools

Direct access to API specification:

📋 Post Templates Guide

What are Post Templates?

Post Templates (also called "Actions" in the backend) are blueprints that define the structure and fields of posts that users can create on your maps. They act as customizable forms that determine what information users can input when creating posts.

💡 Think of it like this:

A Post Template is like a form template - you define what fields users can fill out (text, images, ratings, etc.), and users create posts by filling out those fields.

Key Concepts

🔧 Template vs Post

Post Template: The blueprint/form definition you create
Post: The actual content users create using your template

📝 Versioning System

Post Templates use a versioning system where:

Each template can have multiple versions (drafts and published)
Only published versions can be used to create posts
Existing posts maintain their field structure even when templates are updated
You must specify a version when updating templates

🎯 Featured Fields

Featured fields are special fields that appear prominently in the UI and have strict rules:

Required: At least 1 field must be featured
Maximum: Only 3 fields can be featured per template
Order: Featured fields must appear FIRST in the field arrays
Purpose: Featured fields show in post previews and listings

🚨 Critical Rules & Limitations

⚡ Featured Fields Requirements

MINIMUM: At least 1 field must be featured

MAXIMUM: Only 3 fields can be featured per template

Featured fields appear in post previews. Every template needs at least one featured field.

📍 Featured Fields Order Rule

CRITICAL: Featured fields must have the LOWEST order numbers across ALL field types

When all fields are sorted by their order property (regardless of field type), all featured fields must appear first.

🎬 Media Field Featured Restrictions

Maximum 2 media fields can be featured

If 2 media fields are featured, NO other fields can be featured

This means you can have either: (2 featured media + 0 other featured) OR (0-1 featured media + 1-3 total featured)

🔢 Unique Order Numbers

All order values must be unique across ALL field types

You cannot have two fields with the same order number, even if they're different field types.

🔄 Versioning Requirement

Version must be specified when updating templates

Always include the version field in your update requests.

📅 Date Field Restrictions

Only one date field allowed per template

Date fields have complex validation rules based on their type and duration settings.

🎨 Border Colors

Only predefined colors allowed

Templates must use one of the 22 predefined border colors from the allowed list.

📋 Field Types & Validation Rules

📝 Text Fields

Purpose: Single or multi-line text input

Properties:

label - Display name for the field
placeholder - Hint text for users
required - Whether field must be filled
featured - Whether field appears in previews
order - Display order within field type

🖼️ Media Fields

Purpose: Image and video uploads

Limitations:

Maximum 2 media fields per template
Only accepts valid image/video file IDs
Files must be uploaded separately first
Thumbnail assignment for videos is automatic

🎵 Audio Fields

Purpose: Audio file uploads

Validation:

Only accepts valid audio file IDs
Single audio file per field

🔗 Website Fields

Purpose: URL links with different types

Properties:

linkType - Type of link (Default, Social, etc.)
placeholder - Example URL format

☑️ Select Fields

Purpose: Dropdown or multi-select options

Critical Rules:

Options: 2-30 options allowed
Option Length: 1-25 characters per option
Emoji Consistency: Either ALL options have emojis or NONE do
Multiselect: Must specify if multiple selections allowed

❌ Common Errors:

Mixed emoji usage (some options with emojis, some without)
Too few (<2) or too many (>30) options
Option text too long (>25 characters)
Missing multiselect specification

⭐ Rating Fields

Purpose: 1-5 star ratings

Validation:

Score must be between 1-5
Only integer values allowed

🎚️ Value Slider Fields

Purpose: Numeric range selection

Critical Rules:

Range Validation: min must be less than max
User Input: Selected value must be within defined range

🎛️ Option Slider Fields

Purpose: Predefined option selection via slider

Rules:

Options: 2-4 options allowed
Option Length: 1-20 characters per option
Selection: Index must be valid (0 to options.length-1)

📅 Date Fields

Purpose: Date/time selection with complex rules

Types:

Date - Date only
Time - Time only
DateAndTime - Both date and time

Critical Rules:

Duration Dependency: If using "BasedOnDateField" duration, field must allow time ranges and be required
Range Restrictions: End dates/times only allowed if allowTimeRanges is true
Type Consistency: Field values must match the specified dateType

❌ Common Date Field Errors:

Providing end date when allowTimeRanges is false
Wrong field combination for dateType (e.g., providing time for Date-only field)
Using BasedOnDateField duration without required date field

📊 Duration Types

Duration	Value	Description	Special Rules
Forever	0	Posts never expire	Default option
1 Hour	3600	Posts expire after 1 hour	-
1 Day	86400	Posts expire after 24 hours	-
1 Week	604800	Posts expire after 7 days	-
BasedOnDateField	-1	Posts expire based on date field	Requires date field with allowTimeRanges=true and required=true

🎨 Allowed Border Colors

Templates must use one of these predefined border colors:

#8337EC

#E43AFF

#A86EFF

#87A2FB

#64DFDF

#FF006E

#FF63C1

#FF7D00

#FFAB00

#FFCB00

#C0E218

#00D880

#8DCCFC

#4EA6FD

#802AFF

#3E7C17

#29B23F

#1B939F

#342EAD

#8A9297

#4C5F68

#232932

🛠️ Template Creation Examples

✅ Correct: Featured Fields First

{
  "name": "Restaurant Review",
  "fields": {
    "textFields": [
      {
        "label": "Review Title",
        "featured": true,
        "order": 1          // ✅ Featured field with lowest order
      },
      {
        "label": "Additional Notes", 
        "featured": false,
        "order": 4          // ✅ Non-featured with higher order
      }
    ],
    "ratingFields": [
      {
        "label": "Overall Rating",
        "featured": true,
        "order": 2          // ✅ Featured field with second-lowest order
      }
    ],
    "selectFields": [
      {
        "label": "Meal Type",
        "featured": true,
        "order": 3          // ✅ Featured field with third-lowest order
      }
    ]
  }
}

❌ Incorrect: Featured Fields Not First

{
  "name": "Restaurant Review",
  "emoji": "🍕",
  "mapId": 123,
  "duration": 0,
  "fields": {
    "textFields": [
      {
        "label": "Additional Notes",
        "required": false,
        "featured": false,   // ❌ Non-featured field first
        "order": 1
      },
      {
        "label": "Review Title",
        "required": true,
        "featured": true,    // ❌ Featured field after non-featured
        "order": 2
      }
    ]
  }
}

Error: "Field 'feature:true' should be placed at the first positions on field list"

❌ Common Mistakes

1. Missing Required Featured Field

Creating a template with no featured fields will cause validation errors.

Solution: Ensure at least 1 field is marked as featured.

2. Featured Fields Not at Beginning

Placing featured fields after non-featured fields in arrays causes validation errors.

Solution: Always place featured fields first in each field type array.

3. Too Many Featured Fields

Setting more than 3 fields as featured will cause validation errors.

Solution: Limit featured fields to your 3 most important ones.

4. Too Many Media Fields

Adding more than 2 media fields per template causes validation errors.

Solution: Limit to maximum 2 media fields per template.

5. Invalid Border Color

Using colors not in the predefined list causes validation errors.

Solution: Use only colors from the allowed border colors list.

YouMap Public API

🚀 Getting Started

Overview

Quick Start

Step 3: Getting Your JWT Token

Login Endpoint

Request Body

Example Request

Response

JavaScript Example

Base URL

Making Authenticated Requests

Token Expiration

For Developers & AI Tools

🔑 API Key Generator

Generate Your API Credentials

✅ Your API Credentials

Usage Example:

⚠️ Important Security Notes:

📋 Post Templates Guide

What are Post Templates?

💡 Think of it like this:

Key Concepts

🔧 Template vs Post

📝 Versioning System

🎯 Featured Fields

🚨 Critical Rules & Limitations

⚡ Featured Fields Requirements

📍 Featured Fields Order Rule

🎬 Media Field Featured Restrictions

🔢 Unique Order Numbers

🔄 Versioning Requirement

📅 Date Field Restrictions

🎨 Border Colors

📋 Field Types & Validation Rules

📝 Text Fields

🖼️ Media Fields

🎵 Audio Fields

🔗 Website Fields

☑️ Select Fields

❌ Common Errors:

⭐ Rating Fields

🎚️ Value Slider Fields

🎛️ Option Slider Fields

📅 Date Fields

❌ Common Date Field Errors:

📊 Duration Types

🎨 Allowed Border Colors

🛠️ Template Creation Examples

✅ Correct: Featured Fields First

❌ Incorrect: Featured Fields Not First

❌ Common Mistakes

1. Missing Required Featured Field

2. Featured Fields Not at Beginning

3. Too Many Featured Fields

4. Too Many Media Fields

5. Invalid Border Color