AI-ready version:

Impact Summary Project

Description

The API allows users to retrieve the total impact created for a specific company or application. It also supports filtering the results to display impact data for a specific user.

Endpoint

GET https://impact.dots.eco/api/v1/impact/summary?company={company_id}&app_token={app_token}&user={remote_user_id}

Refer to Headers and Authorization for details on the required headers and authentication tokens.

Parameters

Name	Required	Type	Description
`company`	Yes^*	`integer`	The ID of the company to retrieve its total impact.
`app_token`	Yes^*	`string`	The application token associated with the impact. Multiple tokens should be comma-separated.
`user`	No	`string`	The remote user ID for filtering impact data specific to that particular user.

^*Note: At least one of company or app_token parameters must be provided. If both are provided, the results are filtered further by the app_token.

Example Requests

Minimal Request Example

curl --location --request GET 'https://impact.dots.eco/api/v1/impact/summary?company=1&app_token=65-b156f001' \
--header 'Content-Type: application/json' \
--header 'auth-token: YOUR_AUTH_TOKEN'

Filtering by Multiple App Tokens and User

curl --location --request GET 'https://impact.dots.eco/api/v1/impact/summary?company_id=1&app_token=65-b156f001,63-f1758578&user=testuser' \
--header 'Content-Type: application/json' \
--header 'auth-token: YOUR_AUTH_TOKEN'

Responses

Success Response Example

{
  "1": {
    "project_id": 1,
    "project_name": "Transforming Tanzania's Simiyu Region with Sustainable Forest Gardens and Resilient Agriculture",
    "project_description": "Empower Sukuma farmers in Tanzania's Simiyu region with forest gardens, sustainable agriculture, and vital resources for resilience and abundance.",
    "project_image_url": "https://impact.dots.eco/sites/default/files/2023-11/trees%20for%20thefuture%20tanzania.png",
    "affected_species": [
      {
        "popular_name": "Whitebark Pine",
        "scientific_name": "Pinus albicaulis",
        "IUCN_endangered_status": "Critically Endangered (CR)"
      }
    ],
    "category": [
      {
        "id": 22,
        "name": "Plant Trees",
        "icon": "https://impact.dots.eco/sites/default/files/impact_image/iStock-817552046%2520%25281%2529.jpg",
        "action_in_past_tense": "planted",
        "action_title": "planting",
        "unit_text": "trees",
        "single_unit_text": "tree",
        "unit_html": "<p>trees</p>",
      }
    ],
    "impact_type_id": 3,
    "impact_type_name": "Trees",
    "impact_description": "Planting trees where needed most",
    "impact_unit": "tree",
    "impact_country": "Tanzania",
    "total": "459",
    "logo": "https://impact.dots.eco/sites/default/files/logo/Trees_01-Featured-Image-800x740-1.png",
    "image": "https://impact.dots.eco/sites/default/files/impact_image/iStock-817552046%2520%25281%2529.jpg",
    "unit_text": "trees",
    "unit_html": "<p>trees</p>",
    "geolocation": [
      {
        "lat": -16.271472,
        "lng": 44.446511
      }
    ]
  }
}

Response Fields

Field	Type	Description
`project_id`	`integer`	The unique identifier of the project.
`project_name`	`string`	The name of the project associated with the impact.
`project_description`	`string`	A description of the project’s goals and activities.
`project_image_url`	`string`	A URL pointing to the project’s image.
`affected_species`	`array`	List of species impacted by the project.
`affected_species.popular_name`	`string`	The common name of the affected species.
`affected_species.scientific_name`	`string`	The scientific (Latin) name of the species.
`affected_species.IUCN_endangered_status`	`string`	The IUCN status of the species (e.g., "Critically Endangered (CR)").
`category`	`array`	Impact categories describing the type of project (e.g., planting trees, reducing emissions).
`category.id`	`integer`	The unique identifier of the category type.
`category.name`	`string`	The name of the impact category (e.g., "Plant Trees").
`category.icon`	`string`	A URL pointing to the category’s icon.
`category.action_in_past_tense`	`string`	A past-tense description of the impact action (e.g., "planted").
`category.action_in_past_tense`	`string`	A description of the impact action (e.g., "planting").
`category.unit_text`	`string`	A plain-text representation of the impact unit (e.g., "trees").
`category.sigle_unit_text`	`string`	A plain-text representation of the impact unit (e.g., "tree").
`category.unit_html`	`string`	An HTML-formatted version of the impact unit (e.g., "`<p>trees</p>`").
`impact_type_id`	`integer`	The unique ID of the impact type.
`impact_type_name`	`string`	The name of the impact type (e.g., "Trees").
`impact_description`	`string`	A description of the type of impact made (e.g., "Planting trees where needed most").
`impact_unit`	`string`	The unit type for the impact (e.g., "tree").
`impact_country`	`string`	The country where the impact was made.
`total`	`string`	The total quantity of the specific impact type.
`logo`	`string`	URL to the logo of the organization associated with the project.
`image`	`string`	URL of the image representing the project’s impact type or category.
`unit_text`	`string`	A plain-text representation of the impact unit (e.g., "trees").
`unit_html`	`string`	An HTML-formatted version of the impact unit (e.g., "`<p>trees</p>`").
`geolocation`	`array`	Geographical data for the project's location.
`geolocation.lat`	`float`	Latitude of the project location.
`geolocation.lng`	`float`	Longitude of the project location.

Errors

Possible Error Messages

Message	Cause
`"You must provide a valid 'app_token' and/or 'company'..."`	Neither `app_token` nor `company` provided in the request.
`"No results found for specified criteria."`	The specified parameters didn’t match any impact data (e.g., invalid `app_token`).

HTTP Status Codes

Code	Description
200	Request was successful, and results were returned.
422	Missing or invalid input parameters provided.
404	No results found for the specific query criteria.

Notes

Required Parameters: Provide at least one of company or app_token for the request to be processed.
Multi-App Tokens: You can include multiple application tokens separated by commas for batch queries.
User Filtering: Use the user parameter to further refine results by remote user ID.