Mapping API fields

Understanding Field Mapping

When you receive data from an API, it comes as structured information. For example, an API might return:

Your chosen template (e.g., List) has specific slots where you want to place this data, such as:

• Heading – where the main title goes
• Subheading – where supporting info goes
• Excerpt – where description goes
• Image – where the product image goes

Field mapping connects the API data fields to these template slots. In the example above:

• title (from API) maps to Heading (template)
• description (from API) maps to Excerpt (template)
• image_url (from API) maps to Image (template)
• category (from API) maps to Subheading (template)

How to Map Fields

In the API Press admin, under the Display tab:

1. Choose your template (e.g., List)
2. For each template field, you will see a dropdown or input showing available API fields
3. Select the API field that corresponds to each template slot
4. Save your mappings

The admin interface will show you:

• Available API fields from your response (fetched from the configured endpoint)
• Required fields marked with an asterisk (*)
• Optional fields that you can leave unmapped

Understanding Nested Fields

Some APIs return nested or hierarchical data. For example:

To access nested fields, use dot notation:

• product.name accesses the name field inside product
• product.specs.color accesses the color inside specs

If your API returns an array of multiple levels, you may need to specify the root element first. API Press has a “Root Element” setting to help with this. The Root Element tells API Press where in the response structure to find your data items.

Example: If the API returns { "results": [ { ... }, { ... } ] }, set the Root Element to results to tell API Press to loop through those items.

Using Data Transforms

Transforms allow you to format or modify field values before display. For example, you can:

• Truncate long text to a specific length
• Format dates in a specific way
• Format numbers as currency
• Change text case (uppercase/lowercase)
• Add prefixes or suffixes

Available Transforms

How to Apply Transforms

When mapping a field, you can add transforms to modify the value. You can apply multiple transforms to a single field by chaining them together.

Example: To truncate text to 150 characters and then convert to uppercase:

upper | truncate:150

The transforms are applied in order from left to right.

Transform Examples

Mapping the List Template Fields

Here’s a detailed guide for mapping each field in the List template:

Heading (Required)

The main title of each item. This field is required. Choose the API field that contains the item’s primary identifier or name.

Examples: title, name, product_name

Subheading (Optional)

Secondary text below the heading. Could be a category, author, date, or other detail.

Examples: category, author, date | date:M d, Y

Excerpt (Optional)

Description or preview text. Usually a longer piece of text.

Examples: description, summary | truncate:200

Image (Optional)

URL of an image to display. The field should contain a direct URL to an image file.

Examples: image_url, thumbnail, photo

If the field does not contain a complete URL, use transforms to build it:

image_id | before:https://example.com/images/ | after:.jpg

Link URL (Optional)

Where the item links to when clicked. Should be a complete URL starting with http:// or https://.

Examples: url, link, product_url

If needed, use transforms to build the URL:

product_id | before:https://example.com/products/ | after:/

Button Label (Optional)

The text displayed on the action button. Common values: “Read More”, “View Details”, “Learn More”, “Buy Now”, “View Profile”.

Examples: button_text, action_label

If your API does not have this field, leave it unmapped and set a static value in the template settings.

Badge (Optional)

A small label or tag in the corner. Often used for status or special labels.

Examples: status, tag, priority

Use transforms to format the badge text:

status | upper to show “NEW” or “FEATURED”

Common Mapping Scenarios

Scenario 1: Blog Posts

Scenario 2: Product Listings

Scenario 3: Team Members

Troubleshooting Field Mapping

Field not showing up in the dropdown

Solution: The API response might not have been loaded yet. Click the “Fetch API Data” or “Test Request” button to retrieve the current API response, then refresh the field mapping interface.

Transform not working as expected

Solution: Check that:

• The transform syntax is correct
• The API field contains compatible data (e.g., date transforms need date values)
• Multiple transforms are separated by pipes (|)

Data displaying incorrectly

Solution: Verify that:

• The correct API field is mapped to each template slot
• Field names are spelled exactly as they appear in the API response
• Nested field paths use correct dot notation (e.g., user.name)

Image not displaying

Solution: Check that:

• The image field contains a complete URL with protocol (https://)
• The image URL is publicly accessible
• Use the ensure_prefix:https:// transform if needed

Next Steps

After mapping your fields:

1. Preview the display to make sure the data appears correctly
2. Adjust templates and transforms if needed
3. Move to the next article: Displaying on Your Site to add the API data to your pages