# Datasets

## List all datasets

`$client->datasets->list(): DatasetList`

**get** `/api/v1/datasets`

List all datasets

### Returns

- `DatasetList`

  - `list<Dataset> datasets`

    Array of dataset metadata objects

### Example

```php
<?php

require_once dirname(__DIR__) . '/vendor/autoload.php';

$client = new Client(apiKey: 'My API Key', environment: 'local');

$datasetList = $client->datasets->list();

var_dump($datasetList);
```

#### Response

```json
{
  "datasets": [
    {
      "id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
      "inserted_at": "2019-12-27T18:11:19.117Z",
      "name": "NYC Bike Lanes",
      "slug": "nyc-bike-lanes",
      "updated_at": "2019-12-27T18:11:19.117Z",
      "attribution": "attribution",
      "description": "description",
      "license": "license",
      "source_url": "https://example.com"
    }
  ]
}
```

## Create a new dataset (admin only)

`$client->datasets->create(string name, string slug, ?string attribution, ?string description, ?string license, ?string sourceURL): Dataset`

**post** `/api/v1/datasets`

Create a new dataset (admin only)

### Parameters

- `name: string`

  Human-readable dataset name

- `slug: string`

  URL-friendly identifier (lowercase, hyphens, no spaces)

- `attribution?:optional string`

  Required attribution text

- `description?:optional string`

  Dataset description

- `license?:optional string`

  License identifier (e.g. CC-BY-4.0)

- `sourceURL?:optional string`

  Source data URL

### Returns

- `Dataset`

  - `string id`

    Dataset UUID

  - `\Datetime insertedAt`

    Creation timestamp (UTC)

  - `string name`

    Human-readable dataset name

  - `string slug`

    URL-friendly identifier

  - `\Datetime updatedAt`

    Last update timestamp (UTC)

  - `?string attribution`

    Required attribution text

  - `?string description`

    Dataset description

  - `?string license`

    License identifier (e.g. CC-BY-4.0)

  - `?string sourceURL`

    URL of the original data source

### Example

```php
<?php

require_once dirname(__DIR__) . '/vendor/autoload.php';

$client = new Client(apiKey: 'My API Key', environment: 'local');

$dataset = $client->datasets->create(
  name: 'NYC Bike Lanes',
  slug: 'nyc-bike-lanes',
  attribution: 'attribution',
  description: 'description',
  license: 'license',
  sourceURL: 'https://example.com',
);

var_dump($dataset);
```

#### Response

```json
{
  "id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
  "inserted_at": "2019-12-27T18:11:19.117Z",
  "name": "NYC Bike Lanes",
  "slug": "nyc-bike-lanes",
  "updated_at": "2019-12-27T18:11:19.117Z",
  "attribution": "attribution",
  "description": "description",
  "license": "license",
  "source_url": "https://example.com"
}
```

## Get dataset by ID

`$client->datasets->retrieve(string id): Dataset`

**get** `/api/v1/datasets/{id}`

Get dataset by ID

### Parameters

- `id: string`

### Returns

- `Dataset`

  - `string id`

    Dataset UUID

  - `\Datetime insertedAt`

    Creation timestamp (UTC)

  - `string name`

    Human-readable dataset name

  - `string slug`

    URL-friendly identifier

  - `\Datetime updatedAt`

    Last update timestamp (UTC)

  - `?string attribution`

    Required attribution text

  - `?string description`

    Dataset description

  - `?string license`

    License identifier (e.g. CC-BY-4.0)

  - `?string sourceURL`

    URL of the original data source

### Example

```php
<?php

require_once dirname(__DIR__) . '/vendor/autoload.php';

$client = new Client(apiKey: 'My API Key', environment: 'local');

$dataset = $client->datasets->retrieve('id');

var_dump($dataset);
```

#### Response

```json
{
  "id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
  "inserted_at": "2019-12-27T18:11:19.117Z",
  "name": "NYC Bike Lanes",
  "slug": "nyc-bike-lanes",
  "updated_at": "2019-12-27T18:11:19.117Z",
  "attribution": "attribution",
  "description": "description",
  "license": "license",
  "source_url": "https://example.com"
}
```

## Delete a dataset

`$client->datasets->delete(string id): void`

**delete** `/api/v1/datasets/{id}`

Delete a dataset

### Parameters

- `id: string`

### Example

```php
<?php

require_once dirname(__DIR__) . '/vendor/autoload.php';

$client = new Client(apiKey: 'My API Key', environment: 'local');

$result = $client->datasets->delete('id');

var_dump($result);
```

## Query features in a dataset

`$client->datasets->features(string id, ?string cursor, ?int limit, ?float outputBuffer, ?bool outputCentroid, ?string outputFields, ?bool outputGeometry, ?string outputInclude, ?int outputPrecision, ?float outputSimplify, ?string outputSort): FeatureCollection`

**get** `/api/v1/datasets/{id}/features`

Query features in a dataset

### Parameters

- `id: string`

- `cursor?:optional string`

  Cursor for pagination

- `limit?:optional int`

  Maximum results

- `outputBuffer?:optional float`

  Buffer geometry by meters

- `outputCentroid?:optional bool`

  Replace geometry with centroid

- `outputFields?:optional string`

  Comma-separated property fields to include

- `outputGeometry?:optional bool`

  Include geometry (default true)

- `outputInclude?:optional string`

  Extra computed fields: bbox, distance, center

- `outputPrecision?:optional int`

  Coordinate decimal precision (1-15, default 7)

- `outputSimplify?:optional float`

  Simplify geometry tolerance in meters

- `outputSort?:optional string`

  Sort by: distance, name, osm_id

### Returns

- `FeatureCollection`

  - `list<GeoJsonFeature> features`

    Array of GeoJSON Feature objects

  - `Type type`

    Always `FeatureCollection`

### Example

```php
<?php

require_once dirname(__DIR__) . '/vendor/autoload.php';

$client = new Client(apiKey: 'My API Key', environment: 'local');

$featureCollection = $client->datasets->features(
  'id',
  cursor: 'cursor',
  limit: 0,
  outputBuffer: 0,
  outputCentroid: true,
  outputFields: 'output[fields]',
  outputGeometry: true,
  outputInclude: 'output[include]',
  outputPrecision: 0,
  outputSimplify: 0,
  outputSort: 'output[sort]',
);

var_dump($featureCollection);
```

#### Response

```json
{
  "features": [
    {
      "geometry": {
        "coordinates": [
          2.3522,
          48.8566
        ],
        "type": "Point"
      },
      "properties": {
        "@id": "bar",
        "@type": "bar",
        "amenity": "bar",
        "cuisine": "bar",
        "name": "bar"
      },
      "type": "Feature",
      "id": "node/21154906"
    }
  ],
  "type": "FeatureCollection"
}
```

## Domain Types

### Dataset

- `Dataset`

  - `string id`

    Dataset UUID

  - `\Datetime insertedAt`

    Creation timestamp (UTC)

  - `string name`

    Human-readable dataset name

  - `string slug`

    URL-friendly identifier

  - `\Datetime updatedAt`

    Last update timestamp (UTC)

  - `?string attribution`

    Required attribution text

  - `?string description`

    Dataset description

  - `?string license`

    License identifier (e.g. CC-BY-4.0)

  - `?string sourceURL`

    URL of the original data source

### Dataset List

- `DatasetList`

  - `list<Dataset> datasets`

    Array of dataset metadata objects