# Elements

## Query features by spatial predicate, bounding box, or H3 cell

`$client->elements->query(?string bbox, ?string contains, ?string crosses, ?string cursor, ?string h3, ?string intersects, ?int limit, ?string near, ?float outputBuffer, ?bool outputCentroid, ?string outputFields, ?bool outputGeometry, ?string outputInclude, ?int outputPrecision, ?float outputSimplify, ?string outputSort, ?float radius, ?string touches, ?string type, ?string within): FeatureCollection`

**get** `/api/v1/features`

Query features by spatial predicate, bounding box, or H3 cell

### Parameters

- `bbox?:optional string`

  Legacy shorthand. Bounding box: south,west,north,east. Use spatial predicates (near, within, intersects) instead.

- `contains?:optional string`

  Geometry that features must contain

- `crosses?:optional string`

  Geometry that features must cross

- `cursor?:optional string`

  Cursor for pagination

- `h3?:optional string`

  Legacy shorthand. H3 cell index. Use spatial predicates instead.

- `intersects?:optional string`

  Geometry that features must intersect

- `limit?:optional int`

  Maximum results (default 100, max 10000)

- `near?:optional string`

  Point geometry for proximity search (lat,lng). Requires radius.

- `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

- `radius?:optional float`

  Search radius in meters (for near) or buffer distance (for other predicates)

- `touches?:optional string`

  Geometry that features must touch

- `type?:optional string`

  Element types (comma-separated: node,way,relation)

- `within?:optional string`

  Geometry that features must be within

### 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->elements->query(
  bbox: 'bbox',
  contains: 'contains',
  crosses: 'crosses',
  cursor: 'cursor',
  h3: 'h3',
  intersects: 'intersects',
  limit: 0,
  near: 'near',
  outputBuffer: 0,
  outputCentroid: true,
  outputFields: 'output[fields]',
  outputGeometry: true,
  outputInclude: 'output[include]',
  outputPrecision: 0,
  outputSimplify: 0,
  outputSort: 'output[sort]',
  radius: 0,
  touches: 'touches',
  type: 'type',
  within: 'within',
);

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"
}
```

## Query features by spatial predicate, bounding box, or H3 cell

`$client->elements->queryPost(?string bbox, ?string contains, ?string crosses, ?string cursor, ?string h3, ?string intersects, ?int limit, ?string near, ?float outputBuffer, ?bool outputCentroid, ?string outputFields, ?bool outputGeometry, ?string outputInclude, ?int outputPrecision, ?float outputSimplify, ?string outputSort, ?float radius, ?string touches, ?string type, ?string within): FeatureCollection`

**post** `/api/v1/features`

Query features by spatial predicate, bounding box, or H3 cell

### Parameters

- `bbox?:optional string`

  Legacy shorthand. Bounding box: south,west,north,east. Use spatial predicates (near, within, intersects) instead.

- `contains?:optional string`

  Geometry that features must contain

- `crosses?:optional string`

  Geometry that features must cross

- `cursor?:optional string`

  Cursor for pagination

- `h3?:optional string`

  Legacy shorthand. H3 cell index. Use spatial predicates instead.

- `intersects?:optional string`

  Geometry that features must intersect

- `limit?:optional int`

  Maximum results (default 100, max 10000)

- `near?:optional string`

  Point geometry for proximity search (lat,lng). Requires radius.

- `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

- `radius?:optional float`

  Search radius in meters (for near) or buffer distance (for other predicates)

- `touches?:optional string`

  Geometry that features must touch

- `type?:optional string`

  Element types (comma-separated: node,way,relation)

- `within?:optional string`

  Geometry that features must be within

### 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->elements->queryPost(
  bbox: 'bbox',
  contains: 'contains',
  crosses: 'crosses',
  cursor: 'cursor',
  h3: 'h3',
  intersects: 'intersects',
  limit: 0,
  near: 'near',
  outputBuffer: 0,
  outputCentroid: true,
  outputFields: 'output[fields]',
  outputGeometry: true,
  outputInclude: 'output[include]',
  outputPrecision: 0,
  outputSimplify: 0,
  outputSort: 'output[sort]',
  radius: 0,
  touches: 'touches',
  type: 'type',
  within: 'within',
);

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"
}
```

## Get feature by type and ID

`$client->elements->retrieve(int id, string type): GeoJsonFeature`

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

Get feature by type and ID

### Parameters

- `type: string`

- `id: int`

### Returns

- `GeoJsonFeature`

  - `GeoJsonGeometry geometry`

    GeoJSON Geometry object per RFC 7946. Coordinates use [longitude, latitude] order. 3D coordinates [lng, lat, elevation] are used for elevation endpoints.

  - `array<string,mixed> properties`

    OSM tags flattened as key-value pairs, plus `@type` (node/way/relation) and `@id` (OSM ID) metadata fields. May include `distance_m` for proximity queries.

  - `Type type`

    Always `Feature`

  - `?string id`

    Compound identifier in `type/osm_id` format

### Example

```php
<?php

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

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

$geoJsonFeature = $client->elements->retrieve(0, type: 'type');

var_dump($geoJsonFeature);
```

#### Response

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

## Get feature by type and ID

`$client->elements->lookup(): GeoJsonFeature`

**post** `/api/v1/features/lookup`

Get feature by type and ID

### Returns

- `GeoJsonFeature`

  - `GeoJsonGeometry geometry`

    GeoJSON Geometry object per RFC 7946. Coordinates use [longitude, latitude] order. 3D coordinates [lng, lat, elevation] are used for elevation endpoints.

  - `array<string,mixed> properties`

    OSM tags flattened as key-value pairs, plus `@type` (node/way/relation) and `@id` (OSM ID) metadata fields. May include `distance_m` for proximity queries.

  - `Type type`

    Always `Feature`

  - `?string id`

    Compound identifier in `type/osm_id` format

### Example

```php
<?php

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

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

$geoJsonFeature = $client->elements->lookup();

var_dump($geoJsonFeature);
```

#### Response

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

## Fetch multiple features by type and ID

`$client->elements->batch(list<Element> elements): FeatureCollection`

**post** `/api/v1/features/batch`

Fetch multiple features by type and ID

### Parameters

- `elements: list<Element>`

  Array of element references to fetch

### 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->elements->batch(
  elements: [
    ['id' => 21154906, 'type' => 'node'], ['id' => 4589123, 'type' => 'way']
  ],
);

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"
}
```

## Find features near a geographic point

`$client->elements->nearby(?float lat, ?int limit, ?float lng, ?string near, ?float outputBuffer, ?bool outputCentroid, ?string outputFields, ?bool outputGeometry, ?string outputInclude, ?int outputPrecision, ?float outputSimplify, ?string outputSort, ?int radius): FeatureCollection`

**get** `/api/v1/features/nearby`

Find features near a geographic point

### Parameters

- `lat?:optional float`

  Legacy shorthand. Latitude (-90 to 90). Use near param instead.

- `limit?:optional int`

  Maximum results (default 20, max 100)

- `lng?:optional float`

  Legacy shorthand. Longitude (-180 to 180). Use near param instead.

- `near?:optional string`

  Point geometry for proximity search (lat,lng or GeoJSON). Alternative to lat/lng params.

- `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

- `radius?:optional int`

  Search radius in meters (default 500, max 10000)

### 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->elements->nearby(
  lat: 0,
  limit: 0,
  lng: 0,
  near: 'near',
  outputBuffer: 0,
  outputCentroid: true,
  outputFields: 'output[fields]',
  outputGeometry: true,
  outputInclude: 'output[include]',
  outputPrecision: 0,
  outputSimplify: 0,
  outputSort: 'output[sort]',
  radius: 0,
);

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"
}
```

## Find features near a geographic point

`$client->elements->nearbyPost(?float lat, ?int limit, ?float lng, ?string near, ?float outputBuffer, ?bool outputCentroid, ?string outputFields, ?bool outputGeometry, ?string outputInclude, ?int outputPrecision, ?float outputSimplify, ?string outputSort, ?int radius): FeatureCollection`

**post** `/api/v1/features/nearby`

Find features near a geographic point

### Parameters

- `lat?:optional float`

  Legacy shorthand. Latitude (-90 to 90). Use near param instead.

- `limit?:optional int`

  Maximum results (default 20, max 100)

- `lng?:optional float`

  Legacy shorthand. Longitude (-180 to 180). Use near param instead.

- `near?:optional string`

  Point geometry for proximity search (lat,lng or GeoJSON). Alternative to lat/lng params.

- `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

- `radius?:optional int`

  Search radius in meters (default 500, max 10000)

### 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->elements->nearbyPost(
  lat: 0,
  limit: 0,
  lng: 0,
  near: 'near',
  outputBuffer: 0,
  outputCentroid: true,
  outputFields: 'output[fields]',
  outputGeometry: true,
  outputInclude: 'output[include]',
  outputPrecision: 0,
  outputSimplify: 0,
  outputSort: 'output[sort]',
  radius: 0,
);

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

### Batch Request

- `BatchRequest`

  - `list<Element> elements`

    Array of element references to fetch