# Spot (`spot-1`): Named entity recognition

People, organizations and places, with character offsets.

Spot finds the people, organizations, locations and dates in a text and returns each one with its exact character offsets, so you can highlight, link or index them.

It reads ten languages out of the box. For personal data like emails, phone numbers and IDs, use Veil instead.

- **Price:** $0.02 per 1,000 texts. One unit per text up to 2,000 characters; longer texts are split into 2,000-character chunks and each chunk is a unit.
- **Languages:** Arabic, Chinese, Dutch, English, French, German, Italian, Latvian, Portuguese, Spanish
- **Input:** A string, or an array of up to 64 strings to run as a batch.
- **Batch:** yes, up to 64 inputs per call
- **Status:** live
- **Built on:** [Davlan/distilbert-base-multilingual-cased-ner-hrl](https://huggingface.co/Davlan/distilbert-base-multilingual-cased-ner-hrl), AFL-3.0, 135M (DistilBERT multilingual)

## Request

```bash
curl https://labs.greatwork.company/v1/run \
  -H "Authorization: Bearer $GWL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"spot-1","input":"Satya Nadella met with Ursula von der Leyen in Brussels to discuss Microsoft's new data centers in Ireland."}'
```

## Options

| Name | Type | Required | Default | Description |
|---|---|---|---|---|
| `input` | string or string[] | yes | | A string, or an array of up to 64 strings to run as a batch. |
| `types` | string[] (person \| organization \| location \| date) | no |  | Only return these entity types. |
| `threshold` | number | no | `0.5` | Score at or above which an entity is returned. |

## Output

| Field | Type | Description |
|---|---|---|
| `spans` | object[] | Entities in order: `type`, `text`, `start`, `end` (character offsets, end exclusive), `score`. |
| `counts` | object | How many of each type. |

The response envelope is always `{"id", "object": "run", "model", "created", "output", "usage": {"units", "unit", "cost_usd", "cost_micros"}, "latency_ms"}`. With an array input, `output` is an array in the same order.

## Examples (real outputs from our servers)

### News sentence

```json
{
  "model": "spot-1",
  "input": "Satya Nadella met with Ursula von der Leyen in Brussels to discuss Microsoft's new data centers in Ireland."
}
```

```json
{
  "spans": [
    {
      "type": "person",
      "text": "Satya Nadella",
      "start": 0,
      "end": 13,
      "score": 0.9994
    },
    {
      "type": "person",
      "text": "Ursula von der Leyen",
      "start": 23,
      "end": 43,
      "score": 0.9999
    },
    {
      "type": "location",
      "text": "Brussels",
      "start": 47,
      "end": 55,
      "score": 0.9998
    },
    {
      "type": "organization",
      "text": "Microsoft",
      "start": 67,
      "end": 76,
      "score": 0.9999
    },
    {
      "type": "location",
      "text": "Ireland",
      "start": 99,
      "end": 106,
      "score": 0.9999
    }
  ],
  "counts": {
    "person": 2,
    "location": 2,
    "organization": 1
  }
}
```

35 ms, $0.00002.

### Email

```json
{
  "model": "spot-1",
  "input": "Hi Priya, Marcus from Northwind Traders here. We'll be in Austin on the 14th if you want to meet at the Domain."
}
```

```json
{
  "spans": [
    {
      "type": "person",
      "text": "Priya",
      "start": 3,
      "end": 8,
      "score": 0.9983
    },
    {
      "type": "person",
      "text": "Marcus",
      "start": 10,
      "end": 16,
      "score": 0.9984
    },
    {
      "type": "organization",
      "text": "Northwind Traders",
      "start": 22,
      "end": 39,
      "score": 0.9998
    },
    {
      "type": "location",
      "text": "Austin",
      "start": 58,
      "end": 64,
      "score": 0.9994
    }
  ],
  "counts": {
    "person": 2,
    "organization": 1,
    "location": 1
  }
}
```

30 ms, $0.00002.

### Spanish

```json
{
  "model": "spot-1",
  "input": "Gabriel García Márquez nació en Aracataca y trabajó para El Espectador en Bogotá."
}
```

```json
{
  "spans": [
    {
      "type": "person",
      "text": "Gabriel García Márquez",
      "start": 0,
      "end": 22,
      "score": 0.9999
    },
    {
      "type": "location",
      "text": "Aracataca",
      "start": 32,
      "end": 41,
      "score": 0.9997
    },
    {
      "type": "organization",
      "text": "El Espectador",
      "start": 57,
      "end": 70,
      "score": 0.9995
    },
    {
      "type": "location",
      "text": "Bogotá",
      "start": 74,
      "end": 80,
      "score": 0.9998
    }
  ],
  "counts": {
    "person": 1,
    "location": 2,
    "organization": 1
  }
}
```

19 ms, $0.00002.

## Good for

- Link company and people names in articles
- Build a who-was-mentioned index for transcripts
- Pre-fill CRM fields from emails
- Find locations to geocode

## Limits and caveats

- Four types only: person, organization, location, date.
- Product names and brands are often missed or called organizations.
