# Getting started

import { Card, CardContent, CardDescription, CardFooter, CardHeader, CardTitle } from "zudoku/ui/Card";
import { Button } from "zudoku/ui/Button";
import { Badge } from "zudoku/ui/Badge";
import { Link } from "zudoku/components";
import { ArrowRight, ShieldCheckIcon } from "zudoku/icons";

:::lead
Entur's APIs give developers and partners access to Norway's public transport infrastructure — from open journey planning data to commercial ticket sales integrations. Follow the steps below to get set up.
:::

---

<p className="text-base font-bold mt-8 mb-2 not-prose">Step 1</p>
<div className="[&>h2]:mt-0">

## What do you want to build with Entur

</div>

Depending on your use case, you can use open services, partner services, or combine both.

<div className="grid grid-cols-1 md:grid-cols-2 gap-8 not-prose my-6">
  <Card className="flex flex-col p-6 gap-2 rounded">
    <AudienceBadge audience="open" />
    <CardTitle className="text-xl mt-1">Public transport data APIs</CardTitle>
    <CardDescription>Available to everyone. No partnership agreement required.</CardDescription>
    <hr className="my-3" />
    <ul className="list-disc pl-6 space-y-1 text-sm">
      <li>Journey planner</li>
      <li>Mobility (microtransports, bysykkel..)</li>
      <li>Real-time vehicle positions</li>
      <li>Stops and infrastructure data</li>
    </ul>
    <hr className="my-3" />
    <p className="text-xs uppercase tracking-widest font-semibold text-muted-foreground">Access requirements</p>
    <ul className="list-disc pl-6 space-y-1 text-sm marker:content-['✓_'] marker:text-emerald-600">
      <li>Client identification (ET-Client-Name)</li>
    </ul>
    <div className="mt-auto pt-4">
      <Button variant="link" asChild className="px-0">
        <Link to="/docs/open-services">Learn more <ArrowRight aria-hidden="true" className="ml-1 h-4 w-4" /></Link>
      </Button>
    </div>
  </Card>

  <Card className="flex flex-col p-6 gap-2 rounded">
    <AudienceBadge audience="partner" />
    <CardTitle className="text-xl mt-1">Sales, ticketing & operator APIs</CardTitle>
    <CardDescription>For organisations with a partnership agreement with Entur.</CardDescription>
    <hr className="my-3" />
    <ul className="list-disc pl-6 space-y-1 text-sm">
      <li>Ticket sales and order management</li>
      <li>Timetable and deviations</li>
      <li>Seating and inventory</li>
      <li>Customers and personalisation</li>
    </ul>
    <hr className="my-3" />
    <p className="text-xs uppercase tracking-widest font-semibold text-muted-foreground">Access requirements</p>
    <ul className="list-disc pl-6 space-y-1 text-sm marker:content-['✓_'] marker:text-emerald-600">
      <li>Partnership agreement with Entur</li>
      <li>Client identification (ET-Client-Name)</li>
      <li>OAuth 2.0 authentication</li>
    </ul>
    <div className="mt-auto pt-4">
      <Button variant="link" asChild className="px-0">
        <Link to="/docs/partner-services">Learn more <ArrowRight aria-hidden="true" className="ml-1 h-4 w-4" /></Link>
      </Button>
    </div>
  </Card>
</div>

:::info[Need to become an Entur partner?]
Partner services require a signed agreement with Entur. If your organisation doesn't have one yet, find out how to get started.

[How to become an Entur partner →](https://entur.no/partner)
:::
<p className="mt-8"/>
---

<p className="text-base font-bold mt-8 mb-2 not-prose">Step 2</p>
<div className="not-prose flex items-baseline flex-wrap gap-2 [&>h2]:mt-0">

## Client identification (ET-Client-Name)

<AudienceBadge audience="all" subject="APIs" />

</div>

Every Entur API — open and partner — requires your application to identify itself using the `ET-Client-Name` header. This is always the first step, regardless of which service type you are using.

This helps Entur understand how its APIs are used and allows traffic to be managed responsibly. Requests without this header may be rate limited or blocked.

Use a value that uniquely identifies your company and application, in the form `<company>-<application>` (lowercase, no spaces).

### Example

If your company is "Forsen Utvikling" and your app is "Infoplakat", your `ET-Client-Name` would be `forsen_utvikling-infoplakat`.

```sh
curl --request GET \
  --url "https://api.entur.io/distance/stop-place-distances/NSR:StopPlace:337/NSR:StopPlace:1" \
  --header "ET-Client-Name: forsen_utvikling-infoplakat"
```

<p className="mt-8"/>
---

<p className="text-base font-bold mt-8 mb-2 not-prose">Step 3</p>
<div className="not-prose flex items-baseline flex-wrap gap-2 [&>h2]:mt-0">

## Authentication

<AudienceBadge audience="partner" subject="APIs" />

</div>

If you are only using **Open services**, skip to [step 4](#first-api-call).

Partner APIs require OAuth 2.0 Client Credentials authentication in addition to client identification. See the full guide for setup steps, code examples, environments, and troubleshooting.

<div className="not-prose">
  <Button variant="link" asChild className="px-0">
    <Link to="/docs/authentication">Authentication guide <ArrowRight aria-hidden="true" className="ml-1 h-4 w-4" /></Link>
  </Button>
</div>

---

<p className="text-base font-bold mt-8 mb-2 not-prose">Step 4</p>
<div className="[&>h2]:mt-0">

## First API call

</div>

Try the Geocoder API, as it is open and does not require authentication. This call looks up a stop place by its national ID and returns its name and coordinates.

<OpenPlaygroundButton
  server="https://api.entur.io/geocoder"
  url="/v1/place"
  method="get"
  queryParams={[
    { name: "ids", defaultValue: "NSR:StopPlace:337", defaultActive: true, isRequired: true },
    { name: "lang", defaultValue: "no", defaultActive: true }
  ]}
  headers={[
    { name: "ET-Client-Name", defaultValue: "Entur-Developerportal", defaultActive: true, isRequired: true }
  ]}
/>

```sh
curl "https://api.entur.io/geocoder/v1/place?ids=NSR:StopPlace:337&lang=no" \
  -H "ET-Client-Name: my_company-my_app"
```

---

## Using our docs with AI tools

Every page in the developer portal has a **Copy page** dropdown in the top right corner. Use it to copy the page as Markdown, open it directly in Claude or ChatGPT, or share the link. Doing so on this page is a good starting point for any LLM.

For programmatic access (e.g. adding to `CLAUDE.md` or `AGENTS.md`), we expose:

- [`/llms.txt`](https://beta.developer.entur.no/llms.txt) — the best starting point for any LLM; an index of all doc pages with links to individual Markdown files
- [`/llms-full.txt`](https://beta.developer.entur.no/llms-full.txt) — all documentation in a single file
- Any page as Markdown — append `.md` to its URL (e.g. `/docs/authentication.md`)

---

## Next steps

Now that you are set up, explore the resources below.

<div className="grid grid-cols-1 md:grid-cols-2 gap-4 not-prose my-4">
  <Card className="p-6 gap-2 rounded">
    <p className="text-xs uppercase tracking-widest text-muted-foreground font-medium">Services</p>
    <div className="text-base font-bold!">
      <Link to="/docs/open-services" className="underline font-bold! text-foreground!">Open Services</Link>
      <span className="text-muted-foreground mx-2 font-normal!">|</span>
      <Link to="/docs/partner-services" className="underline font-bold! text-foreground!">Partner Services</Link>
    </div>
    <CardDescription>Explore what you can build with open and partner services.</CardDescription>
  </Card>

  <Card className="p-6 gap-2 rounded">
    <p className="text-xs uppercase tracking-widest text-muted-foreground font-medium">How-to guides</p>
    <Link to="/guides" className="text-base font-bold! underline text-foreground!">Guides</Link>
    <CardDescription>Step-by-step instructions for achieving specific integration goals.</CardDescription>
  </Card>

  <Card className="p-6 gap-2 rounded">
    <p className="text-xs uppercase tracking-widest text-muted-foreground font-medium">Understanding</p>
    <Link to="/concepts" className="text-base font-bold! underline text-foreground!">Concepts</Link>
    <CardDescription>The ideas and standards behind Entur's ecosystem.</CardDescription>
  </Card>

  <Card className="p-6 gap-2 rounded">
    <p className="text-xs uppercase tracking-widest text-muted-foreground font-medium">Reference</p>
    <Link to="/apis/open" className="text-base font-bold! underline text-foreground!">API catalogue</Link>
    <CardDescription>Browse all Entur APIs with full endpoint and parameter reference.</CardDescription>
  </Card>
</div>