Feature API

The Feature API lets you store, retrieve and list GeoJSON features inside your collections. Features follow the GeoJSON specification.

Access Token

Before accessing the Feature API, you need a valid access token. You can get your access tokens in your Jawg App account.

All requests must include the access-token query parameter:

https://api.jawg.io/collections/{id}/features?access-token={your-access-token}

Feature object

Features conform to the GeoJSON Feature type:

{
  "type": "Feature",
  "id": "stop-42",
  "geometry": {
    "type": "Point",
    "coordinates": [2.3488, 48.8534]
  },
  "properties": {
    "name": "Châtelet",
    "line": "1"
  }
}

If no id is set on the feature when it is put into a collection, a UUID is generated automatically.

Put a single feature

Inserts or replaces a single GeoJSON feature in a collection. If the feature already has an id, it is used as the key (upsert semantics). If there is no id, one is generated.

PUT https://api.jawg.io/collections/{collectionId}/features?access-token={your-access-token}
Content-Type: application/json

Path parameters

• collectionId required: The identifier of the target collection.

Request body

A single GeoJSON Feature object:

{
  "type": "Feature",
  "id": "stop-42",
  "geometry": {
    "type": "Point",
    "coordinates": [2.3488, 48.8534]
  },
  "properties": {
    "name": "Châtelet",
    "line": "1"
  }
}

Response

// HTTP 200 OK

{
  "type": "Feature",
  "id": "stop-42",
  "geometry": {
    "type": "Point",
    "coordinates": [2.3488, 48.8534]
  },
  "properties": {
    "name": "Châtelet",
    "line": "1"
  }
}

Error codes

Put multiple features (streaming)

Inserts or replaces a stream of GeoJSON features in a collection. Features are sent as line-delimited JSON (application/x-ndjson), one feature per line. Returns a report summarising how many features were processed.

PUT https://api.jawg.io/collections/{collectionId}/features?access-token={your-access-token}
Content-Type: application/x-ndjson

Path parameters

• collectionId required: The identifier of the target collection.

Request body

One GeoJSON Feature object per line:

{"type":"Feature","id":"stop-42","geometry":{"type":"Point","coordinates":[2.3488,48.8534]},"properties":{"name":"Châtelet"}}
{"type":"Feature","id":"stop-43","geometry":{"type":"Point","coordinates":[2.3514,48.8566]},"properties":{"name":"Les Halles"}}

Response

// HTTP 200 OK

{
  "total": 2,
  "successful": 1,
  "failures": {
    "total": 1,
    "failures": [
      {
        "id": "stop-43",
        "reason": "Invalid geometry"
      }
    ]
  }
}

Error codes

Retrieve a feature

Returns a single feature by its collection and feature id.

GET https://api.jawg.io/collections/{collectionId}/features/{featureId}?access-token={your-access-token}

Path parameters

• collectionId required: The identifier of the collection.
• featureId required: The identifier of the feature.

Response

// HTTP 200 OK

{
  "type": "Feature",
  "id": "stop-42",
  "geometry": {
    "type": "Point",
    "coordinates": [2.3488, 48.8534]
  },
  "properties": {
    "name": "Châtelet",
    "line": "1"
  }
}

Error codes

Delete a feature

Removes a single feature from a collection.

DELETE https://api.jawg.io/collections/{collectionId}/features/{featureId}?access-token={your-access-token}

Path parameters

• collectionId required: The identifier of the collection.
• featureId required: The identifier of the feature to delete.

Response

HTTP 204 No Content

Error codes

List features

Returns features from one or more collections as a GeoJSON FeatureCollection. Results are paginated via a Link header.

GET https://api.jawg.io/collections/{collectionIds}/features?access-token={your-access-token}
Accept: application/json

Path parameters

• collectionIds required: One or more collection identifiers, separated by +.

  Example: my-bus-stops+my-poi lists both the my-bus-stops collection and the my-poi collection.

Query parameters

• bbox optional (string): Bounding box filter in the format minLon,minLat,maxLon,maxLat. Only features whose geometry intersects this box are returned. Example: 2.2241,48.8156,2.4699,48.9022

• limit optional (integer): Maximum number of features to return. Must be between 1 and 500000.

• after optional (string): Pagination cursor. Use the value from the Link header of the previous response to fetch the next page. The format is {collectionId}.{featureId}.

• size optional (string): Maximum total response size. Must be between 1MB and 10MB. Defaults to 10MB. Example: 5MB

• {propertyName} optional (string): Filter features by a property value. Any query parameter not listed above is interpreted as a property filter. Only features whose properties.{propertyName} matches the given value are returned. Multiple filters are combined with AND. Example: line=1 returns only features where properties.line equals "1".

Pagination

When more results are available, the response includes a Link header pointing to the next page:

Link: </collections/my-bus-stops/features?after=my-bus-stops.stop-42&limit=100>; rel="next"

Pass the after value from this header in your next request to retrieve the following page. When the Link header is absent, you have reached the last page.

Response

// HTTP 200 OK
// Link: </collections/my-bus-stops/features?after=my-bus-stops.stop-43>; rel="next"

{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "id": "stop-42",
      "geometry": { "type": "Point", "coordinates": [2.3488, 48.8534] },
      "properties": { "name": "Châtelet", "line": "1" }
    },
    {
      "type": "Feature",
      "id": "stop-43",
      "geometry": { "type": "Point", "coordinates": [2.3514, 48.8566] },
      "properties": { "name": "Les Halles", "line": "1" }
    }
  ]
}

Error codes

Stream features (NDJSON)

Returns features from one or more collections as a line-delimited JSON stream. Unlike the list endpoint, this endpoint streams all matching features without pagination.

GET https://api.jawg.io/collections/{collectionIds}/features?access-token={your-access-token}
Accept: application/x-ndjson

Path parameters

• collectionIds required: One or more collection identifiers, separated by +.

Query parameters

• bbox optional (string): Bounding box filter in the format minLon,minLat,maxLon,maxLat.

• {propertyName} optional (string): Filter features by a property value. See List features for details.

Response

Each line of the response body is a GeoJSON Feature object:

// HTTP 200 OK
// Content-Type: application/x-ndjson

{"type":"Feature","id":"stop-42","geometry":{"type":"Point","coordinates":[2.3488,48.8534]},"properties":{"name":"Châtelet","line":"1"}}
{"type":"Feature","id":"stop-43","geometry":{"type":"Point","coordinates":[2.3514,48.8566]},"properties":{"name":"Les Halles","line":"1"}}

Error codes