> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fetchin.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Search Geo IDs

> Find the geo ID of a place from its name, to filter job searches by location

## Endpoint

```
GET /api/v1/geo-id/search
```

## Authentication

Include your API key in the request header:

```bash theme={null}
X-API-Key: your-api-key-here
```

## Parameters

**search** `string` *required*

The place to look up, as you would type it in a location filter: a city
(`Lyon`), a region (`Île-de-France`), a metropolitan area or a country
(`France`). At most 100 characters.

## Response

**elements** `array`

The places matching the text, best match first (up to 20), the same
suggestions a location filter's autocompletion offers.

**Place object**

**geoId** `string` *required*

The place's numeric ID, to pass as `geoId` to
[Search Jobs](https://docs.fetchin.io/api-reference/endpoint/search-jobs.md).

**title** `string` *required*

The place's full name (e.g. `"Lyon, Auvergne-Rhône-Alpes, France"`,
`"Greater Lyon Area"`).

## Example Request

```bash cURL theme={null}
curl -G "https://api.fetchin.io/api/v1/geo-id/search" \
  --data-urlencode "search=Lyon" \
  -H "X-API-Key: your-api-key-here"
```

```javascript JavaScript theme={null}
const response = await fetch(
  `https://api.fetchin.io/api/v1/geo-id/search?search=${encodeURIComponent('Lyon')}`,
  { headers: { 'X-API-Key': 'your-api-key-here' } },
);

const { elements } = await response.json();
console.log(elements[0]); // { geoId: '103815258', title: 'Lyon, Auvergne-Rhône-Alpes, France' }
```

```python Python theme={null}
import requests

response = requests.get(
    'https://api.fetchin.io/api/v1/geo-id/search',
    headers={'X-API-Key': 'your-api-key-here'},
    params={'search': 'Lyon'},
)

print(response.json()['elements'][:3])
```

## Example Response

```json 200 Success theme={null}
{
  "elements": [
    { "geoId": "103815258", "title": "Lyon, Auvergne-Rhône-Alpes, France" },
    { "geoId": "90009674", "title": "Greater Lyon Area" },
    { "geoId": "106252843", "title": "Lyons, Illinois, United States" },
    { "geoId": "104757301", "title": "South Lyon, Michigan, United States" },
    { "geoId": "104495668", "title": "Sainte-Foy-lès-Lyon, Auvergne-Rhône-Alpes, France" }
  ]
}
```

```json 400 Bad Request theme={null}
{
  "error": "Missing search parameter",
  "code": "MISSING_PARAMETER"
}
```

```json 401 Unauthorized theme={null}
{
  "error": "Invalid API key",
  "code": "INVALID_API_KEY"
}
```

```json 402 Payment Required theme={null}
{
  "error": "Quota exceeded. Upgrade your plan or wait for renewal.",
  "code": "QUOTA_EXHAUSTED",
  "details": {
    "creditsRemaining": 0,
    "subscriptionCreditsRemaining": 0,
    "paygCreditsRemaining": 0,
    "buyCreditsUrl": "https://fetchin.io/credits"
  }
}
```

```json 503 Service Unavailable theme={null}
{
  "error": "Service temporarily unable to serve this request. Please retry.",
  "code": "SERVICE_UNAVAILABLE"
}
```

## Errors

See [Error Handling](https://docs.fetchin.io/concepts/error-handling.md) for the full list of error codes and recommended handling.

* `400` — `MISSING_PARAMETER` / `INVALID_PARAMETER`
* `401` — `INVALID_API_KEY`
* `402` — `QUOTA_EXHAUSTED`
* `429` — `RATE_LIMITED`
* `500` — `INTERNAL_ERROR`
* `503` — `SERVICE_UNAVAILABLE`

A text that matches no place answers `200` with an empty `elements` list.

## Notes

> [!NOTE]
>
> This endpoint consumes 1 credit per call. Errors are free. See [Quotas](https://docs.fetchin.io/concepts/quotas.md).

> [!TIP]
>
> A geo ID is stable: look it up once and keep it. Passing a `location`
> text to [Search Jobs](https://docs.fetchin.io/api-reference/endpoint/search-jobs.md) does this lookup
> for you on every call and keeps the first suggestion.


## OpenAPI

````yaml GET /api/v1/geo-id/search
openapi: 3.1.0
info:
  title: Fetchin API
  version: 1.0.0
  description: Public B2B data API for fetching posts and profile information
servers:
  - url: https://api.fetchin.io
    description: Production server
security:
  - ApiKeyAuth: []
paths:
  /api/v1/geo-id/search:
    get:
      summary: Search geo IDs
      description: >-
        The places matching a location text, best match first (up to 20), each
        with the geo ID that GET /api/v1/jobs/search takes as `geoId`. One
        credit.
      parameters:
        - name: search
          in: query
          required: true
          description: >-
            The place to look up: a city, region, metropolitan area or country
            (at most 100 characters).
          schema:
            type: string
            example: Lyon
      responses:
        '200':
          description: Matching places
          content:
            application/json:
              schema:
                type: object
                properties:
                  elements:
                    type: array
                    items:
                      type: object
                      required:
                        - geoId
                        - title
                      properties:
                        geoId:
                          type: string
                          example: '103815258'
                        title:
                          type: string
                          example: Lyon, Auvergne-Rhône-Alpes, France
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
components:
  responses:
    BadRequest:
      description: Bad request - a required parameter is missing or a value is invalid.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            missingParameter:
              value:
                error: Missing profileUrlOrUrn parameter
                code: MISSING_PARAMETER
            invalidParameter:
              value:
                error: limit must be a number between 1 and 100
                code: INVALID_PARAMETER
            invalidUrn:
              value:
                error: 'Invalid URN format: urn:li:member:123456789'
                code: INVALID_URN
    Unauthorized:
      description: Unauthorized - the X-API-Key header is missing or invalid.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            missingApiKey:
              value:
                error: Missing API key. Include X-API-Key header.
                code: UNAUTHENTICATED
            invalidApiKey:
              value:
                error: Invalid API key
                code: INVALID_API_KEY
    PaymentRequired:
      description: >-
        Payment required - you are out of credits (QUOTA_EXHAUSTED): the plan
        allowance for the current period is spent AND no pay-as-you-go credits
        are left. Buy pay-as-you-go credits (self-serve,
        https://fetchin.io/credits), upgrade your plan, or wait for renewal;
        retrying will not help and no Retry-After is sent. Distinct from the
        per-second rate limit, which is a 429 (RATE_LIMITED).
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            quotaExhausted:
              value:
                error: Quota exceeded. Upgrade your plan or wait for renewal.
                code: QUOTA_EXHAUSTED
                details:
                  creditsRemaining: 0
                  subscriptionCreditsRemaining: 0
                  paygCreditsRemaining: 0
                  buyCreditsUrl: https://fetchin.io/credits
    TooManyRequests:
      description: >-
        Too many requests - your per-second rate limit (RATE_LIMITED) was
        exceeded. Back off and retry, honoring the Retry-After header. (Running
        out of credits is a separate 402 PaymentRequired / QUOTA_EXHAUSTED, and
        buying credits never raises this per-second limit.)
      headers:
        Retry-After:
          description: Number of seconds to wait before retrying the request.
          schema:
            type: integer
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            rateLimited:
              value:
                error: Rate limit exceeded. Try again later.
                code: RATE_LIMITED
    InternalError:
      description: >-
        Internal server error - an unexpected error occurred in our API. Safe to
        retry; contact support if it persists.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            internalError:
              value:
                error: Internal server error
                code: INTERNAL_ERROR
    ServiceUnavailable:
      description: >-
        Service unavailable - our API is temporarily unable to serve this
        request (capacity exhausted or overloaded). This is on our side, not
        yours and not an upstream service outage. Retry with backoff, honoring
        the Retry-After header.
      headers:
        Retry-After:
          description: Number of seconds to wait before retrying the request.
          schema:
            type: integer
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            serviceUnavailable:
              value:
                error: >-
                  Service temporarily unable to serve this request. Please
                  retry.
                code: SERVICE_UNAVAILABLE
  schemas:
    Error:
      type: object
      required:
        - error
        - code
      properties:
        error:
          type: string
          description: >-
            Human-readable description of what went wrong. For display/logging;
            do not branch on this string.
        code:
          type: string
          enum:
            - MISSING_PARAMETER
            - INVALID_PARAMETER
            - INVALID_URN
            - UNAUTHENTICATED
            - INVALID_API_KEY
            - FORBIDDEN
            - NOT_FOUND
            - PROFILE_NOT_FOUND
            - POST_NOT_FOUND
            - COMPANY_NOT_FOUND
            - ENDPOINT_REMOVED
            - RATE_LIMITED
            - QUOTA_EXHAUSTED
            - INTERNAL_ERROR
            - UPSTREAM_ERROR
            - SERVICE_UNAVAILABLE
            - UPSTREAM_TIMEOUT
          description: >-
            Stable, machine-readable error code. Branch your integration on this
            value, not on the HTTP status alone or the message text.
        details:
          type: object
          additionalProperties: true
          description: >-
            Optional structured context. On QUOTA_EXHAUSTED it carries the
            balance breakdown at the moment of the rejection - creditsRemaining,
            subscriptionCreditsRemaining, paygCreditsRemaining - plus
            buyCreditsUrl, the self-serve page for buying more credits. Always
            additive and never guaranteed: read it for diagnostics and logs, but
            branch on `code` and do not require any field of it.
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.