> ## Documentation Index
> Fetch the complete documentation index at: https://docs.scanoss.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Geoprovenance API

> Retrieve geographical provenance of software components using contributor locations, commit timing patterns, and development activity.

## CountryContributorsByComponents

Get geographical provenance for multiple components based on contributor declared locations and curated analysis.

### HTTP Request Example

```bash theme={null}
curl -X POST 'https://api.scanoss.com/v2/geoprovenance/countries/components' \
  -H 'Content-Type: application/json' \
  -H "X-Api-Key: $SC_API_KEY" \
  -d '{
    "components": [
      {"purl": "pkg:github/scanoss/engine@5.0.0"}
    ]
  }' | jq
```

### Response Format

Returns geographical provenance data per component.

* `purl` — Component Package URL identifier
* `declared_locations` — Locations reported by contributors in profiles or repository metadata
* `curated_locations` — SCANOSS-derived geographic distribution
* `status` — Request outcome (success or failure)

### Response Examples

#### Component with Geographic Distribution

```json theme={null}
{
  "components_locations": [
    {
      "purl": "pkg:github/scanoss/engine@5.0.0",
      "declared_locations": [
        {
          "type": "owner",
          "location": "Barcelona, Spain"
        },
        {
          "type": "contributor",
          "location": "Berlin, Germany"
        }
      ],
      "curated_locations": [
        {
          "country": "Spain",
          "count": 8
        },
        {
          "country": "Germany",
          "count": 3
        },
        {
          "country": "United States",
          "count": 2
        }
      ]
    }
  ],
  "status": {
    "status": "SUCCESS",
    "message": "Geo-provenance successfully retrieved"
  }
}
```

#### Component with Limited Geographic Data

```json theme={null}
{
  "components_locations": [
    {
      "purl": "pkg:npm/simple-utility@1.0.0",
      "declared_locations": [],
      "curated_locations": [
        {
          "country": "United States",
          "count": 1
        }
      ]
    }
  ],
  "status": {
    "status": "SUCCESS",
    "message": "Geo-provenance successfully retrieved"
  }
}
```

#### Error in component

When a component cannot be processed, the response includes error fields:

* `error_code`: Machine-readable error identifier
* `error_message`: Human-readable explanation

```json theme={null}
{
  "components_locations": [
    {
      "purl": "pkg:github/torvalds/linux",
      "declared_locations": [],
      "curated_locations": [],
      "error_message": "Too many contributors for a component",
      "error_code": "TOO_MANY_CONTRIBUTORS"
    }
  ],
  "status": {
    "status": "SUCCESS",
    "message": "Geo-provenance successfully retrieved"
  }
}
```

## CountryContributorsByComponent

Get geographical provenance for a single software component based on contributor declared locations and curated analysis.

### HTTP Request Example

```bash theme={null}
curl -X GET 'https://api.scanoss.com/v2/geoprovenance/countries/component?purl=pkg:github/scanoss/engine@5.0.0' \
  -H "X-Api-Key: $SC_API_KEY" | jq
```

### Response Format

Returns geographical provenance data per component.

* `purl` — Component Package URL identifier
* `declared_locations` — Locations reported by contributors in profiles or repository metadata
* `curated_locations` — SCANOSS-derived geographic distribution
* `status` — Request outcome (success or failure)

### Response Examples

#### Component with Geographic Distribution

```json theme={null}
{
  "component_locations": {
    "purl": "pkg:github/scanoss/engine@5.0.0",
    "declared_locations": [
      {
        "type": "owner",
        "location": "Barcelona, Spain"
      },
      {
        "type": "contributor",
        "location": "Berlin, Germany"
      }
    ],
    "curated_locations": [
      {
        "country": "Spain",
        "count": 8
      },
      {
        "country": "Germany",
        "count": 3
      },
      {
        "country": "United States",
        "count": 2
      }
    ]
  },
  "status": {
    "status": "SUCCESS",
    "message": "Geo-provenance successfully retrieved"
  }
}
```

#### Component with Limited Geographic Data

```json theme={null}
{
  "component_locations": {
    "purl": "pkg:npm/simple-utility@1.0.0",
    "declared_locations": [],
    "curated_locations": [
      {
        "country": "United States",
        "count": 1
      }
    ]
  },
  "status": {
    "status": "SUCCESS",
    "message": "Geo-provenance successfully retrieved"
  }
}
```

#### Error in component

When a component cannot be processed, the response includes error fields:

* `error_code`: Machine-readable error identifier
* `error_message`: Human-readable explanation

```json theme={null}
{
  "component_locations": {
    "purl": "pkg:github/torvalds/linux",
    "declared_locations": [],
    "curated_locations": [],
    "error_message": "Too many contributors for a component",
    "error_code": "TOO_MANY_CONTRIBUTORS"
  },
  "status": {
    "status": "SUCCESS",
    "message": "Geo-provenance successfully retrieved"
  }
}
```

## GetOriginByComponents

Retrieves geographical origin information based on contributor commit timing patterns and development activity analysis. This method examines when contributors are most active to infer their likely geographical locations.

### HTTP Request Example

```bash theme={null}
curl -X POST 'https://api.scanoss.com/v2/geoprovenance/origin/components' \
  -H 'Content-Type: application/json' \
  -H "X-Api-Key: $SC_API_KEY" \
  -d '{
    "components": [
      {"purl": "pkg:github/scanoss/engine@5.0.0"}
    ]
  }' | jq
```

### Response Format

Returns commit-time based geographical origin analysis per component.

* `components_locations` — List of origin results derived from commit activity patterns
* `status` — Request outcome (success or failure)

Each item in `components_locations` includes:

* `purl` — Component Package URL identifier
* `locations` — Country distribution inferred from commit timing analysis, expressed as percentage contribution per region

### Response Examples

#### Component with Origin Analysis

```json theme={null}
{
  "components_locations": [
    {
      "purl": "pkg:github/scanoss/engine@5.0.0",
      "locations": [
        {
          "name": "ES",
          "percentage": 65.5
        },
        {
          "name": "DE",
          "percentage": 20.3
        },
        {
          "name": "US",
          "percentage": 14.2
        }
      ]
    }
  ],
  "status": {
    "status": "SUCCESS",
    "message": "Geo-provenance origin successfully retrieved"
  }
}
```

#### Component with Single Origin

```json theme={null}
{
  "components_locations": [
    {
      "purl": "pkg:npm/private-utility@2.1.0",
      "locations": [
        {
          "name": "US",
          "percentage": 100.0
        }
      ]
    }
  ],
  "status": {
    "status": "SUCCESS",
    "message": "Geo-provenance origin successfully retrieved"
  }
}
```

#### Error in component

When a component cannot be processed, the response includes error fields:

* `error_code`: Machine-readable error identifier
* `error_message`: Human-readable explanation

```json theme={null}
{
  "components_locations": [
    {
      "purl": "pkg:github/torvalds/linux",
      "locations": [],
      "error_message": "Too many contributors for a component",
      "error_code": "TOO_MANY_CONTRIBUTORS"
    }
  ],
  "status": {
    "status": "SUCCESS",
    "message": "Geo-provenance origin successfully retrieved"
  }
}
```

## GetOriginByComponent

Get geographical origin for multiple components based on commit timing and activity patterns.

### HTTP Request Example

```bash theme={null}
curl -X GET 'https://api.scanoss.com/v2/geoprovenance/origin/component?purl=pkg:github/scanoss/engine@5.0.0' \
  -H "X-Api-Key: $SC_API_KEY"
```

### Response Format

Returns commit-time based geographical origin analysis per component.

* `components_locations` — List of origin results derived from commit activity patterns
* `status` — Request outcome (success or failure)

Each item in `components_locations` includes:

* `purl` — Component Package URL identifier
* `locations` — Country distribution inferred from commit timing analysis, expressed as percentage contribution per region

### Response Examples

#### Component with Origin Analysis

```json theme={null}
{
  "component_locations": {
    "purl": "pkg:github/scanoss/engine@5.0.0",
    "locations": [
      {
        "name": "ES",
        "percentage": 65.5
      },
      {
        "name": "DE",
        "percentage": 20.3
      },
      {
        "name": "US",
        "percentage": 14.2
      }
    ]
  },
  "status": {
    "status": "SUCCESS",
    "message": "Geo-provenance origin successfully retrieved"
  }
}
```

#### Component with Single Origin

```json theme={null}
{
  "component_locations": {
    "purl": "pkg:npm/private-utility@2.1.0",
    "locations": [
      {
        "name": "US",
        "percentage": 100.0
      }
    ]
  },
  "status": {
    "status": "SUCCESS",
    "message": "Geo-provenance origin successfully retrieved"
  }
}
```

#### Error in component

When a component cannot be processed, the response includes error fields:

* `error_code`: Machine-readable error identifier
* `error_message`: Human-readable explanation

```json theme={null}
{
  "component_locations": {
    "purl": "pkg:github/torvalds/linux",
    "locations": [],
    "error_message": "Too many contributors for a component",
    "error_code": "TOO_MANY_CONTRIBUTORS"
  },
  "status": {
    "status": "SUCCESS",
    "message": "Geo-provenance origin successfully retrieved"
  }
}
```