Getting started overview

Integrating with Izi primarily involves accessing and managing tour content through their platform. The Izi developer experience focuses on tools for content partners to publish and retrieve information related to cultural institutions, city tours, and self-guided experiences. This guide details the process of setting up a developer account, obtaining necessary credentials, and executing a basic API call to retrieve content. Unlike transactional APIs, Izi's API is designed for content management and retrieval rather than dynamic user interactions.

The Izi platform supports partners in creating and distributing multimedia tours. Its API enables programmatic access to tour data, allowing developers to integrate Izi content into their own applications or services. This process typically involves registering as a content provider, using the Izi Content Management System (CMS) to populate tour data, and then leveraging the API to retrieve that data or public content.

Quick Reference: Izi Getting Started

Step What to Do Where
1 Register for a content provider account Izi Developer Portal
2 Access the Izi CMS and verify credentials Izi Content Management System
3 Locate API documentation for data endpoints Izi API Reference
4 Construct a sample API request for public content Izi Developer Documentation examples
5 Execute the API call and verify data retrieval Your preferred HTTP client or programming language

Create an account and get keys

To begin using Izi's developer features, you must first register for a content provider account. This account grants access to the Izi Content Management System (CMS), which is central to managing and publishing tour content, and indirectly provides access to the API for retrieving that content. Izi's model emphasizes content creation and distribution, making the CMS an integral part of the developer workflow.

  1. Register for an Izi account: Navigate to the Izi developer portal and follow the instructions to create a new content provider account. This typically involves providing an email address, setting a password, and agreeing to the terms of service.
  2. Verify your account: After registration, you may receive an email to verify your account. Complete this step to activate your content provider access.
  3. Access the Izi CMS: Once your account is active, log in to the Izi Content Management System. The CMS is where you create, edit, and publish tours and related multimedia content. While the Izi documentation does not explicitly detail an API key generation process akin to many other APIs, your access to the content and its retrieve via API is linked to your authenticated CMS account and its associated published content. The API is primarily for querying published content rather than performing actions requiring unique API keys for each request.
  4. Understand Izi's API access model: Izi's API provides access to publicly available tour content and content associated with your authenticated content provider account. The developer documentation focuses on the structure of API endpoints for data retrieval and does not typically require a unique API key sent with every request for publicly accessible data. For more specific access or content management functionalities, consult the Izi API documentation for any authentication headers or parameters that might be required for specific endpoints.

The Izi platform is free for content creators to develop and publish tours, operating on a revenue-share model for premium content. This means initial setup and content creation do not incur direct costs, aligning with its mission to support cultural institutions and tour operators in digital storytelling.

Your first request

Making your first request to the Izi API involves identifying an endpoint for public content and constructing a standard HTTP GET request. Since Izi's API focuses on content retrieval and does not typically require per-request API keys for public data, the process is similar to accessing any public RESTful endpoint. For this example, we will aim to retrieve a list of tours or a specific tour's data.

The Izi developer documentation provides details on available endpoints and data structures. A common starting point is an endpoint that lists tours or specific objects within a tour. We'll use a conceptual endpoint for demonstration, as exact public endpoints may vary and are best confirmed in the Izi API reference.

Example: Retrieving a list of tours (Conceptual)

Assume an endpoint similar to https://izi.travel/api/v2/tours exists for retrieving tour information. You would perform a simple GET request. For demonstration, we'll use curl, a common command-line tool for making HTTP requests, as described in Mozilla's web HTTP documentation.

Using curl:

curl -X GET "https://api.izi.travel/v2/tours?lang=en&limit=10"

In this example:

  • -X GET specifies the HTTP method as GET.
  • "https://api.izi.travel/v2/tours" is the hypothetical base URL for the tours endpoint.
  • ?lang=en&limit=10 are query parameters to filter results (e.g., language in English, limit to 10 tours). Actual parameters are specified in the official Izi API documentation.

Expected Response (JSON):

A successful response would return a JSON object containing an array of tour data. The structure will conform to the Izi API specification. For instance:

{
  "data": [
    {
      "uuid": "tour-uuid-123",
      "title": "Historical City Walk",
      "description": "Explore the city's rich history.",
      "language": "en",
      "duration": "1h 30m",
      "image_url": "https://izi.travel/images/tour1.jpg"
    },
    {
      "uuid": "tour-uuid-456",
      "title": "Museum Highlights Tour",
      "description": "A curated tour of museum masterpieces.",
      "language": "en",
      "duration": "2h 0m",
      "image_url": "https://izi.travel/images/tour2.jpg"
    }
  ],
  "pagination": {
    "total": 100,
    "offset": 0,
    "limit": 10
  }
}

This response demonstrates the typical JSON format for retrieving tour data, including unique identifiers (UUIDs), titles, descriptions, and other relevant metadata. Always refer to the Izi API documentation for the precise structure and available fields for each endpoint.

Common next steps

After successfully making your first API call to Izi, several common next steps can help you further integrate and leverage the platform:

  1. Explore specific content endpoints: The Izi API likely offers various endpoints beyond a general tour list, such as those for specific objects within a tour, media files, or location-based queries. Consult the Izi API reference to understand the full range of data you can access.
  2. Implement filtering and pagination: For larger datasets, learn how to use query parameters for filtering results (e.g., by language, category, location) and pagination (e.g., offset, limit) to efficiently retrieve data.
  3. Integrate with your application: Begin integrating the retrieved Izi data into your user interface or backend services. This might involve parsing the JSON response and displaying tour information, maps, or audio content within your application.
  4. Content creation and management: If you plan to publish your own tours, familiarize yourself with the Izi CMS. This system is crucial for creating and managing multimedia content that can then be retrieved via the API.
  5. Review usage policies: Understand Izi's terms of service and any API usage policies, especially concerning rate limits, data attribution, and commercial use. This ensures compliance and sustainable integration.
  6. Consider advanced features: Investigate any advanced features such as real-time updates (if available), webhooks for content changes, or specialized SDKs if Izi offers them for specific platforms.

Troubleshooting the first call

When making your initial API request to Izi, you might encounter issues. Here are common problems and troubleshooting steps:

  • Incorrect Endpoint URL: Double-check the base URL and endpoint path against the Izi API documentation. Typos are a frequent cause of 404 Not Found errors.
  • Network Connectivity Issues: Ensure your machine has an active internet connection and no firewall or proxy is blocking the request. Tools like ping or checking other websites can help diagnose general connectivity problems.
  • Invalid Query Parameters: If your request includes query parameters (e.g., lang, limit), verify that their names and values match the API specification. Incorrect parameters might lead to empty responses or 400 Bad Request errors.
  • HTTP Status Codes:
    • 400 Bad Request: Often indicates an issue with your request's format or parameters. Review your query string and ensure it adheres to the API's requirements.
    • 403 Forbidden / 401 Unauthorized: While Izi's public content API doesn't always require explicit keys per request, if you're attempting to access private content or specific administrative endpoints, you might need proper authentication. Consult the API documentation for required headers or tokens for such cases.
    • 404 Not Found: The most common cause is an incorrect URL or an endpoint that no longer exists or has moved.
    • 5xx Server Error: These indicate a problem on the Izi server side. If you consistently receive 5xx errors, it might be a temporary platform issue. Check the Izi developer portal or status page (if available) for announcements.
  • JSON Parsing Errors: If the API returns data but your application can't parse it, ensure your JSON parser is correctly implemented. Verify that the response is indeed valid JSON using an online validator if necessary.
  • Refer to Developer Documentation: The Izi API documentation is the authoritative source for troubleshooting specific endpoints and error messages. Look for sections on error handling or frequently asked questions.