POST /geo_id_search • Credits: 0.01 credits per call

Geo ID Search turns a location name into the LinkedIn geo ID that other RichAPI search endpoints accept. Send a POST request with one search value, and the response returns an elements array of matched locations. Each geoId value is a string. Each call costs 0.01 credits, or $0.0002.

What does Geo ID Search do?

LinkedIn filters people and companies by a numeric geo ID, not by a location name. Geo ID Search closes that gap. Send a place name such as San Francisco Bay Area. Geo ID Search returns every LinkedIn location that matches the text, with the geo ID of each one. Pass the geo ID that you want into the geo_ids parameter of Lead Search, into the geo_id parameter of Profile Search and LinkedIn Company Search, or into the geoId parameter of LinkedIn Job Search. The data source is LinkedIn, and Geo ID Search returns no people and no companies.

Which endpoint does Geo ID Search use?

Method: POST
URL: https://api.richapi.ai/api/v1/geo_id_search
Authentication: x-api-key header
Request format: JSON request body
Response: synchronous JSON
Credits: 0.01 credits per call

Geo ID Search accepts the POST method only. If you send GET, the API returns 405 with the error geo_id_search only supports POST. Send the search parameter in the request body. The API reads no query string parameter.

How to send a Geo ID Search request

Copy your API key from the RichAPI dashboard.
Set search to the location name, for example San Francisco Bay Area.
Send a POST request to https://api.richapi.ai/api/v1/geo_id_search.
Send the API key in the x-api-key header.
Set the Content-Type header to application/json.
Read the matches from the elements array in the response.
Copy the geoId value of the match that you want.

cURL

curl -X POST https://api.richapi.ai/api/v1/geo_id_search   
  -H "x-api-key: YOUR_API_KEY"   
  -H "Content-Type: application/json"   
  -d '{
    "search": "San Francisco Bay Area"
  }'

Python

import requests

response = requests.post(
    "https://api.richapi.ai/api/v1/geo_id_search",
    headers={"x-api-key": "YOUR_API_KEY"},
    json={
        "search": "San Francisco Bay Area",
    },
    timeout=60,
)
response.raise_for_status()
print(response.json())

Node.js

const response = await fetch("https://api.richapi.ai/api/v1/geo_id_search", {
  method: "POST",
  headers: {
    "x-api-key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    search: "San Francisco Bay Area",
  }),
});

const data = await response.json();
console.log(data);

What parameters does Geo ID Search accept?

Geo ID Search accepts one parameter. Send it in the JSON request body.

Parameter	Type	Required	Default	Description
`search`	string	Yes	`""`	The location name to search, for example `San Francisco` or `London`.

What does Geo ID Search return?

This block is an example response for the request body {"search": "San Francisco Bay Area"}. The geoId and title values change with the location that you search.

{
  "elements": [
    {
      "geoId": "90000084",
      "title": "San Francisco Bay Area"
    },
    {
      "geoId": "102277331",
      "title": "San Francisco, California, United States"
    },
    {
      "geoId": "90000079",
      "title": "San Jose, California, United States"
    }
  ]
}

Which fields does the Geo ID Search response hold?

Field	Type	Description
`elements`	array	The list of matched geo entries.
`elements[].geoId`	string	The LinkedIn geo ID to use in search filters.
`elements[].title`	string	The human-readable location name.

How to use Geo ID Search with Lead Search

Geo ID Search has value in a pair. Step 1 resolves the place name. Step 2 runs the real search with the resolved ID.

Step 1 — resolve the location name

curl -X POST https://api.richapi.ai/api/v1/geo_id_search   
  -H "x-api-key: YOUR_API_KEY"   
  -H "Content-Type: application/json"   
  -d '{
    "search": "San Francisco Bay Area"
  }'

Read the elements array. Pick the entry whose title matches the region that you want. In the example response above, that entry is San Francisco Bay Area with the geo ID 90000084.

Step 2 — send the geo ID to Lead Search

Set geo_ids to an array that holds the geo ID from step 1.

curl -X POST https://api.richapi.ai/api/v1/lead_search   
  -H "x-api-key: YOUR_API_KEY"   
  -H "Content-Type: application/json"   
  -d '{
    "search_query": "founder",
    "geo_ids": ["90000084"],
    "seniority": ["Senior", "Director"],
    "page": 1
  }'

What do the two steps cost together?

Step	Endpoint	Credits
1	Geo ID Search	0.01
2	Lead Search, one full page of 25 profiles	22.5
Total		22.51

Lead Search costs 10 credits per call plus 0.5 credits per returned profile. A full page of 25 profiles costs 10 + (25 x 0.5) = 22.5 credits. The two steps together cost 22.51 credits. That is $0.4502. Step 1 adds 0.04 percent to the cost of step 2.

When does RichAPI resolve a location name for you?

The geo_ids and exclude_geo_ids parameters of Lead Search accept numeric geo IDs and location names. If you send a name, RichAPI calls the same location lookup for you before the search runs. Four rules apply to that inline lookup:

Rule	Behavior
Maximum names per field	10. A longer list returns `400`.
Match used	The first entry of the lookup result only.
Timeout per lookup	10 seconds, and never more than the time left in the request deadline.
Deadline breach	The API returns `504` with the error `Geo location lookup exceeded the request deadline`.

Geo ID Search gives you two things that the inline lookup does not. It shows every match, so you pick the correct one and do not take the first entry. It also returns an ID that you store and send again. A stored geo ID needs no lookup, so a later Lead Search call cannot fail with 504 or 502.

How much does Geo ID Search cost?

Geo ID Search costs 0.01 credits per call. One credit costs $0.02 on the 1,000 and 5,000 credit packs, so one call costs $0.0002 there. Geo ID Search is one of the cheapest paid endpoints in RichAPI. Usage and inquiry endpoints are free. Resolve as many place names as you want. The cost stays near zero.

Calls	Credits	Cost
1	0.01	$0.0002
100	1	$0.02
10,000	100	$2.00

One hundred Geo ID Search calls cost 1 credit. Ten thousand calls cost 100 credits, or $2.00. RichAPI reserves the credits before the call and refunds them for any response outside the 200 range.

Which errors can Geo ID Search return?

Status	Meaning	What to do
`400`	The request body failed validation. A request body without a `search` value causes this failure.	Set `search` to a location name in the request body.
`401`	The API key is missing, wrong or revoked.	Send a valid key in the `x-api-key` header.
`402`	`Insufficient credits`: the organization has too few credits. Or `Monthly spend limit reached`: the team hit its monthly spend limit.	Buy credits in the RichAPI dashboard, or ask the organization owner to raise the spend limit.
`403`	`Endpoint not available on your plan`: this API key has no access to this endpoint.	Call `GET /api/v1/my-endpoints` to list the endpoints this key can use. Contact support for access.
`405`	The request used a method other than `POST`.	Send the request again with the `POST` method.
`429`	Too many requests.	Read the `Retry-After` header. Wait that many seconds, then send the request again.
`500`	The API failed.	Send the request again. If the failure repeats, contact support.

An unknown place name is not an error. Geo ID Search returns 200 with an empty elements array.

Frequently asked questions

Does Geo ID Search accept a GET request?

No. Geo ID Search accepts POST only, and it returns 405 for every other method. Send the search parameter in the JSON request body, never in the query string.

How much does one Geo ID Search call cost?

One Geo ID Search call costs 0.01 credits. At $0.02 per credit that is $0.0002 per call, so 100 calls cost 1 credit.

Do I have to call Geo ID Search before Lead Search?

No. The geo_ids parameter of Lead Search also accepts a plain location name, and RichAPI resolves it during the request. Geo ID Search is useful because it shows every match, and because a stored geo ID removes the lookup from the later request.

How do I choose the correct entry in the response?

Read the title value of each entry in the elements array. Pick the entry whose title names the region that you want, then copy its geoId value.

Can I store a geo ID and use it again?

Yes. Store the geoId value and send it in later requests. A stored geo ID costs no further Geo ID Search call.

Which RichAPI endpoints accept a geo ID?

Lead Search accepts geo IDs in the geo_ids and exclude_geo_ids parameters. Profile Search and LinkedIn Company Search accept a single geo ID in the geo_id parameter. LinkedIn Job Search takes it in geoId.

What does Geo ID Search return for a place name that LinkedIn does not know?

Geo ID Search returns status 200 with an empty elements array. Send a broader location name, for example the country instead of the city.

Does a failed Geo ID Search request cost credits?

No. RichAPI refunds the credit reservation for every response outside the 200 range. A 400, 429 or 500 response costs no credit.

Geo ID Search API